Webhooks#

Les modes asynchrones de l'API (émission async=true, lots) produisent le PDF en file d'attente, quelques secondes après la réponse 201/202. Sans webhooks, vous suivez l'avancement en sondant GET /documents/{public_id}/pdf ou GET /batches/{batch_id}. Avec un webhook, DokKraft vous prévient dès que l'état change — le sondage reste la source de vérité, le webhook est une optimisation (une livraison peut être perdue : votre handler doit tolérer de ne rien recevoir). Les événements document couvrent en outre le cycle de vie de tout document de l'espace, émis depuis l'API comme depuis l'interface, un lot ou une automatisation.

Déclarer un endpoint#

Les webhooks sont inclus à partir du plan Pro (ils complètent l'API asynchrone) — un espace Free ou Starter les consulte en lecture seule. Dans DokKraft : Paramètres → Webhooks. Chaque espace de travail peut déclarer jusqu'à 10 endpoints ; un endpoint s'abonne à un sous-ensemble des événements ci-dessous. À la création, un secret (whsec_…) s'affiche une seule fois — stockez-le immédiatement. Il peut être régénéré à tout moment (l'ancien cesse de signer immédiatement).

Événements#

Un événement supplémentaire, ping, est la livraison de test : envoyez-en une à tout moment avec le bouton « Tester » de l'endpoint (ou juste après sa création) pour valider votre URL et votre vérification de signature sans émettre un vrai document. Son payload contient un message et l'identifiant de l'endpoint.

Événement	Émis quand	Données
ping	Livraison de test (bouton « Tester » de l'interface)	message, endpoint
document.emitted	Un document a été émis (numéro réservé + snapshot figés) — API, interface, lot ou automatisation	document : publicId, name, number, status, pdfUrl
document.pdf_ready	Le rendu PDF d'un document est terminé et stocké	idem, status vaut ready
document.pdf_failed	Le rendu a définitivement échoué (essais épuisés)	idem + errorCode, errorMessage
document.cancelled	Un document a été annulé (statut terminal, pièce neutralisée)	idem, status vaut annule
batch.completed	Un lot a atteint son état final (completed, partial ou failed)	batch : publicId, status, counts (emitted, failed), completedAt
automation.run.completed	Une automatisation a traité une occurrence (émission/livraison terminée)	automationId, runId, documentId, status (emitted|sent), mode (notify|email|none)

Les identifiants de documents, lots et règles d'automatisation sont les mêmes que dans l'API REST : récupérez le détail avec GET /documents/{publicId} ou GET /batches/{publicId}. Le PDF lui-même n'est jamais dans le payload — téléchargez-le via pdfUrl.

Le corps reçu est une enveloppe commune :

{
  "id": "0b6e0f2e-…",
  "event": "document.pdf_ready",
  "createdAt": "2026-09-22T14:03:11+00:00",
  "data": {
    "document": {
      "publicId": "doc_…",
      "name": "Facture ABC",
      "number": "FA-2026-0042",
      "status": "ready",
      "pdfUrl": "https://dokkraft.blocsland.com/api/v1/documents/doc_…/pdf"
    }
  }
}

Exemple d'enveloppe pour automation.run.completed :

{
  "id": "7c1d94a0-…",
  "event": "automation.run.completed",
  "createdAt": "2026-09-30T09:00:04+00:00",
  "data": {
    "automationId": "e3a1c07e-…",
    "runId": 42,
    "documentId": "9f2b6d41-…",
    "status": "sent",
    "mode": "email"
  }
}

status reflète l'issue du run (emitted en livraison « notification », sent après un envoi email) ; mode rappelle le canal déclaré sur la règle (notify, email ou none).

Vérifier la signature#

Chaque livraison porte les en-têtes X-DokKraft-Event, X-DokKraft-Delivery et X-DokKraft-Signature au format t=<horodatage>,v1=<hmac>. Le HMAC est un HMAC-SHA256 de "{t}.{corps_brut}" clé avec le secret de l'endpoint — signez le corps exact reçu (pas une ré-encodage JSON), puis comparez les deux v1 à constante près.

Vérification de référence (PHP) :

$parts = [];
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_DOKKRAFT_SIGNATURE']), $parts);
$expected = hash_hmac('sha256', $parts['t'] . '.' . file_get_contents('php://input'), $secret);
if (! hash_equals($expected, $parts['v1'] ?? '')) {
    http_response_code(401); // signature invalide — pas une livraison DokKraft
    exit;
}
if (abs(time() - (int) $parts['t']) > 300) {
    http_response_code(401); // livraison trop ancienne — rejouer ou ignorer
    exit;
}

Livraison et réessais#

• Une livraison répondant 2xx est considérée aboutie ; toute autre réponse (ou un délai > 5 s) déclenche une nouvelle tentative.
• Réessais : 1 min, 10 min, 1 h, 6 h (5 essais au total), puis la livraison est abandonnée. Elle reste visible et rejouable dans Paramètres → Webhooks.
• Idempotence : un même événement n'est jamais livré deux fois au même endpoint. En revanche, votre handler peut recevoir deux événements distincts dans un ordre quelconque — filtrez par document.status si besoin.
• Plafond quotidien : les livraisons sont limitées à 1 000 par jour et par espace (tous endpoints confondus). Au-delà, les livraisons du jour ne sont plus créées — les événements émis ensuite ne vous parviennent pas ; le compteur repart au lendemain.
• Désactiver un endpoint (interrupteur) coupe ses livraisons immédiatement, sans perdre son historique.
• Coupure automatique : après 20 livraisons abandonnées consécutives (URL qui ne répond jamais 2xx), l'endpoint est coupé automatiquement pour ne pas consommer la quota de livraisons — l'interface le marque « Coupé (échecs) » et le réactiver est un clic sur l'interrupteur.