Webhooks — receive signature events in real time

Payload format

Every delivery shares the same top-level JSON schema: `event`, `data` and `timestamp`. The event name is repeated in the `X-Certyneo-Event` header too, so you can route before parsing the body at all. The contents of `data` vary per event, but always stay a flat object of simple values — never an array, never a nested object. Here is a complete `envelope.completed` delivery.

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 a presigned link valid for 7 days from the event: it saves you a second authenticated call to fetch the PDF. It is absent — not null — when presigning failed, or on a QES envelope completed without a stored document; fall back to GET /v1/envelopes/id/signed-document, which remains the source of truth. Mind manual dead-letter-queue replays more than 7 days after the event too: the link in the payload has expired, the API endpoint has not.

The payload is UTF-8 encoded, no BOM. The HMAC signature is computed over the raw body as transmitted — don't reformat whitespace; re-parsing JSON often reorders keys and breaks verification.

Verify the HMAC signature

Every request is signed with your webhook secret (displayed only once, when the subscription is created). The signature travels in the `X-Certyneo-Signature` header: it is the HMAC-SHA256 of the raw request body, hex-encoded, with no prefix and no timestamp. ALWAYS verify the signature before processing the payload — without that step, anyone can forge an event and call your 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)

Retry policy

If your endpoint takes too long to answer, refuses the connection or returns a 5xx (or a 429), we retry with exponential backoff: 5 attempts in all, over roughly 1 h 20. After the fifth the event goes to the dead-letter queue — still listed and replayable from your dashboard, but no longer retried automatically. An outright refusal (401, 403, 404, 410, 422…) is never retried: the answer would not change, so the event goes straight to the dead-letter queue.

The delays above are minimums: the retry sweep is driven by a cron, so an attempt can fire slightly after its theoretical time. Abandoned events are listed under Webhooks → Failures, with a manual replay button and no retention limit. An endpoint that racks up five final failures — or answers 404 / 410 — is disabled automatically and you are told by email: re-enable it once fixed and the counter starts from zero (any successful delivery resets it too).

Test without sending a real envelope

Create a subscription first — the response carries the `secret` you need for HMAC verification, shown only once. From Settings → Webhooks, the « Test » button then sends a signed POST exactly like a real delivery and shows you your server's raw response: it is the fastest way to validate your handler, locally through ngrok or in continuous integration.

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

The URL must be publicly reachable over HTTPS: a private or localhost address is rejected by the SSRF guard when the subscription is created.

Subscriptions are split by environment, like the keys: a webhook created with an sk_test_ key receives only the events of test envelopes, a webhook created with an sk_live_ key only those of real envelopes. A test envelope therefore never reaches your production URL, and every payload states "sandbox" (true or false).

Learn more

• Developer hub
• E-signature API
• Native integrations
• Security page
• Plans & pricing