Webhooks
La plateforme vous prévient ; vous ne sondez pas. Chaque livraison est signée, rejouée jusqu’à huit fois, et vérifiable en trois lignes.
Créer un endpoint
curl -X POST https://preprod-app.signatik.com/api/v1/webhook-endpoints -H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" -d '{ "url": "https://votre-app.fr/webhooks/esign" }'
# → 201 { "id": "…", "url": "…", "secret": "whsec_…", "active": true } ← secret affiché UNE foisÉvénements
| Événement | Quand | Charge utile |
|---|---|---|
envelope.completed | après scellement (toutes les signatures recueillies, cachet apposé) | enveloppe complète avec liens de téléchargement (1 h) |
envelope.expired | date d’expiration dépassée sans complétion | identifiant, nom, statut |
mandate.activated | acte de mandat signé par le représentant | mandat |
seal_batch.applied | lot cacheté | lot, enveloppes |
attendance.session_closed | session clôturée et feuille scellée | session |
Vérifier la signature
En-têtes : X-Esign-Event et X-Esign-Signature: sha256=<hex>, HMAC-SHA256 du corps brut avec votre secret. Comparez en temps constant.
●Node
const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers['x-esign-signature']));●PHP
$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
$ok = hash_equals($expected, $_SERVER['HTTP_X_ESIGN_SIGNATURE']);●Python
expected = 'sha256=' + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
ok = hmac.compare_digest(expected, request.headers['X-Esign-Signature'])Attention
Vérifiez la signature sur le corps brut, avant tout parsing. Un corps re-sérialisé (espaces, ordre des clés) ne correspond plus.
Reprises et idempotence
Une réponse autre que 2xx déclenche jusqu’à 8 nouvelles tentatives avec attente exponentielle (30 s, 60 s, 120 s…). Traitez chaque événement de façon idempotente : l’identifiant d’enveloppe et le type suffisent à dédupliquer. Répondez 2xx vite et traitez en asynchrone.