Webhooks — ontvang handtekeningsgebeurtenissen in realtime

Payload-indeling

Alle leveringen delen hetzelfde JSON-schema op het hoogste niveau: `event`, `data` en `timestamp`. De naam van de gebeurtenis wordt ook herhaald in de header `X-Certyneo-Event`, wat routering mogelijk maakt voordat u zelfs maar de body parseert. De inhoud van `data` varieert per gebeurtenis, maar blijft altijd een plat object met eenvoudige waarden — nooit een array of genest object. Hier is een volledige `envelope.completed`-levering.

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

{
  "id": "cm8f2h6a10004qr9k5p2wm3xt",
  "event": "envelope.completed",
  "data": {
    "envelopeId": "cm7x2k9p40001qz8h3f7bn2ld",
    "sandbox": false,
    "subject": "Contrat de prestation Acme Corp",
    "status": "COMPLETED",
    "signatureLevel": "ADVANCED",
    "aesSignerCount": 2,
    "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 is een vooraf ondertekende koppeling die 7 dagen geldig is vanaf de gebeurtenis: hiermee wordt een tweede geverifieerde aanroep voor het ophalen van de PDF vermeden. Dit is afwezig — en niet null — als de vooraf-ondertekening is mislukt, of op een QES-envelop die zonder opgeslagen document is voltooid; gebruik dan GET /v1/envelopes/id/signed-document, wat de waarheid blijft. Let ook op handmatige replay vanuit de dead-letter queue meer dan 7 dagen na de gebeurtenis: de koppeling in de payload is verlopen, het API-eindpunt niet.

De payload is UTF-8 gecodeerd, zonder BOM. De HMAC-handtekening wordt berekend op het onbewerkte body zoals verzonden — wijzig geen spaties, herparsen van JSON wijzigt vaak de volgorde van sleutels en verbreekt de verificatie.

HMAC-handtekening verifiëren

Elke verzoek wordt ondertekend met uw webhookgeheim (weergegeven slechts één keer bij het maken van het abonnement). De handtekening wordt doorgegeven in de header `X-Certyneo-Signature`: dit is de HMAC-SHA256 van de ruwe requestbody, gecodeerd in hexadecimaal, zonder voorvoegsel of timestamp. Verifieer ALTIJD de handtekening voordat u de payload verwerkt — zonder deze stap kan iedereen een gebeurtenis vervalsen en uw eindpunt aanroepen.

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)

Beleid voor opnieuw proberen

Als uw endpoint te lang duurt om te antwoorden, de verbinding weigert of een 5xx (of 429) retourneert, doen wij opnieuw een poging volgens exponentiële backoff: 5 pogingen in totaal, over ongeveer 1 u 20 min. Na de vijfde poging gaat de gebeurtenis naar de dead-letter queue — inzichtelijk en opnieuw af te spelen vanaf uw dashboard, maar niet meer automatisch opnieuw geprobeerd. Een expliciete weigering (401, 403, 404, 410, 422…) wordt echter nooit opnieuw geprobeerd: het antwoord zou niet veranderen, de gebeurtenis gaat direct naar de dead-letter queue.

De aangegeven termijnen zijn minima: de herhalingsscan wordt ingesteld door een cron, dus een poging kan iets na het theoretische moment plaatsvinden. Verlaten gebeurtenissen worden vermeld in Webhooks → Fouten, met een handmatige afspeelknop en zonder bewaarlimieten. Een endpoint met vijf opeenvolgende definitieve fouten — of die 404/410 antwoordt — wordt automatisch uitgeschakeld en u wordt hiervan per e-mail op de hoogte gesteld: reactiveer het eenmaal hersteld, de teller begint opnieuw (elke succesvolle bezorging stelt het ook op nul).

Testen zonder een echte envelop te verzenden

Maak eerst een abonnement — het antwoord bevat het `secret` dat nodig is voor HMAC-verificatie, slechts eenmaal weergegeven. Vanuit Instellingen → Webhooks stuurt de knop "Testen" vervolgens een ondertekend POST precies zoals een echte levering en toont u het ruwe antwoord van uw server: dit is de snelste manier om uw handler te valideren, lokaal via ngrok of in continue integratie.

# 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"]
  }'

De URL moet openbaar bereikbaar zijn via HTTPS: een privé-adres of localhost wordt bij abonnementcreatie afgewezen door SSRF-bescherming.

Abonnementen zijn per omgeving gescheiden, net als de sleutels: een webhook die met een sk_test_-sleutel is aangemaakt, ontvangt alleen de gebeurtenissen van testenveloppen, een webhook met een sk_live_-sleutel alleen die van echte enveloppen. Een testenvelop bereikt uw productie-URL dus nooit, en elke payload vermeldt „sandbox” (true of false).

Meer informatie

• Ontwikkelaarhub
• API elektronische handtekening
• Native integraties
• Beveiligingspagina
• Plannen en prijzen