Webhooks — recevez les événements de signature en temps réel

Format du payload

Toutes les livraisons partagent le même schéma JSON top-level : `event`, `data` et `timestamp`. Le nom de l'événement est aussi répété dans l'en-tête `X-Certyneo-Event`, ce qui permet de router avant même de parser le corps. Le contenu de `data` varie selon l'événement, mais reste toujours un objet plat de valeurs simples — jamais de tableau ni d'objet imbriqué. Voici une livraison `envelope.completed` complète.

POST /webhooks/certyneo HTTP/1.1
Host: your.app
Content-Type: application/json
X-Certyneo-Event: envelope.completed
X-Certyneo-Signature: 4f3d1c8b2a9e7f60d5c4b3a2918e7f6d5c4b3a2918e7f6d5c4b3a2918e7f6d5c

{
  "event": "envelope.completed",
  "data": {
    "envelopeId": "cm7x2k9p40001qz8h3f7bn2ld",
    "subject": "Contrat de prestation Acme Corp",
    "status": "COMPLETED",
    "completedAt": "2026-05-27T08:42:13.000Z",
    "recipientCount": 2,
    "recipients": [
      { "email": "alice@acme.com", "name": "Alice Martin", "role": "SIGNER", "status": "SIGNED" },
      { "email": "bob@acme.com", "name": "Bob Durand", "role": "SIGNER", "status": "SIGNED" }
    ],
    "signedDocumentUrl": "https://storage.certyneo.com/signed/cm7x2k9p4.../contrat.pdf?X-Amz-Expires=604800&X-Amz-Signature=..."
  },
  "timestamp": "2026-05-27T08:42:13.521Z"
}

signedDocumentUrl est un lien pré-signé valable 7 jours à compter de l'événement : il évite un second appel authentifié pour récupérer le PDF. Il est absent — et non pas null — si la pré-signature a échoué, ou sur une enveloppe QES complétée sans document stocké ; repassez alors par GET /v1/envelopes/id/signed-document, qui reste la source de vérité. Attention aussi au rejeu manuel depuis la dead-letter queue plus de 7 jours après l'événement : le lien du payload est expiré, l'endpoint API non.

Le payload est encodé UTF-8, sans BOM. La signature HMAC est calculée sur le body brut tel qu'envoyé — n'altérez pas les espaces, le re-parsing JSON modifie souvent l'ordre des clés et casse la vérification.

Vérifier la signature HMAC

Chaque requête est signée avec votre secret webhook (affiché une seule fois à la création de l'abonnement). La signature est transmise dans l'en-tête `X-Certyneo-Signature` : c'est le HMAC-SHA256 du corps brut de la requête, encodé en hexadécimal, sans préfixe ni horodatage. Vérifiez TOUJOURS la signature avant de traiter le payload — sans cette étape, n'importe qui peut forger un événement et appeler votre endpoint.

import crypto from "node:crypto";

export function verifyCertyneoSignature(
  rawBody: string,
  signatureHeader: string,
  secret: string,
): boolean {
  // X-Certyneo-Signature = HMAC-SHA256(secret, rawBody), hex-encoded.
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  const received = Buffer.from(signatureHeader, "hex");
  const computed = Buffer.from(expected, "hex");

  // timingSafeEqual throws when the two buffers differ in length —
  // a malformed header must return false, not crash the handler.
  if (received.length !== computed.length) return false;

  // timingSafeEqual to mitigate timing attacks.
  return crypto.timingSafeEqual(computed, received);
}

import hashlib
import hmac


def verify_certyneo_signature(
    raw_body: bytes, signature_header: str, secret: str
) -> bool:
    """Verify a Certyneo webhook signature.

    `X-Certyneo-Signature` holds the hex-encoded HMAC-SHA256 of the
    raw request body, computed with your webhook secret.
    """
    expected = hmac.new(
        secret.encode("utf-8"),
        raw_body,
        hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(expected, signature_header)

Politique de retry

Si votre endpoint met trop de temps à répondre, refuse la connexion ou renvoie un 5xx (ou un 429), nous retentons selon un backoff exponentiel : 5 tentatives au total, sur environ 1 h 20. Passé la cinquième, l'événement part en dead-letter queue — consultable et rejouable depuis votre dashboard, mais plus retenté automatiquement. Un refus explicite (401, 403, 404, 410, 422…) n'est en revanche jamais retenté : la réponse ne changerait pas, l'événement part directement en dead-letter queue.

Les délais indiqués sont des minimums : le balayage de retry est cadencé par un cron, une tentative peut donc partir légèrement après l'heure théorique. Les événements abandonnés sont listés dans Webhooks → Échecs, avec un bouton de rejeu manuel et sans limite de durée de conservation. Un endpoint qui enchaîne cinq échecs définitifs — ou qui répond 404 / 410 — est désactivé automatiquement, et vous en êtes prévenu par email : réactivez-le une fois corrigé, le compteur repart de zéro (toute livraison réussie le remet également à zéro).

Tester sans envoyer de vraie enveloppe

Créez d'abord un abonnement — la réponse contient le `secret` nécessaire à la vérification HMAC, affiché une seule fois. Depuis Paramètres → Webhooks, le bouton « Tester » envoie ensuite un POST signé exactement comme une vraie livraison et vous affiche la réponse brute de votre serveur : c'est le moyen le plus rapide de valider votre handler, en local via ngrok ou en intégration continue.

# Create a subscription — "secret" is returned once, store it now.
curl -X POST https://api.certyneo.com/v1/webhooks \
  -H "Authorization: Bearer $CERTYNEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your.app/webhooks/certyneo",
    "events": ["envelope.completed", "recipient.signed"]
  }'

L'URL doit être publiquement joignable en HTTPS : une adresse privée ou localhost est rejetée par la protection SSRF au moment de la création de l'abonnement.

Pour aller plus loin

• Hub développeur
• API signature électronique
• Intégrations natives
• Page sécurité
• Plans et tarifs