Webhooks — receive signature events in real time

Payload format

Every event shares the same top-level JSON schema: `event`, `envelope_id`, `occurred_at`, `data`. The contents of `data` vary by event (per-event fields documented in the API reference). Here is a complete `envelope.completed` example.

{
  "event": "envelope.completed",
  "envelope_id": "env_01HG3K8X9Y2N4P5Q6R7S8T9V0W",
  "occurred_at": "2026-05-27T08:42:13.521Z",
  "data": {
    "title": "Contrat de prestation Acme Corp",
    "status": "completed",
    "created_at": "2026-05-24T14:12:00.000Z",
    "completed_at": "2026-05-27T08:42:13.000Z",
    "signers": [
      {
        "email": "client@acme.example",
        "name": "Alex Client",
        "signed_at": "2026-05-27T08:42:13.000Z",
        "method": "eidas_aes",
        "ip": "203.0.113.42"
      }
    ],
    "proof_pdf_url": "https://certyneo.com/api/envelopes/env_01HG.../proof.pdf"
  }
}

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 (shown once at creation in the dashboard, then encrypted at rest). The signature is transmitted in the `Certyneo-Signature` header as `t=<timestamp>,v1=<hex_hmac>`. ALWAYS verify the signature before processing the payload — without this 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 {
  // Header format: t=<timestamp>,v1=<hex_hmac>
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((p) => p.split("=")),
  );
  const ts = parts.t;
  const sig = parts.v1;
  if (!ts || !sig) return false;

  // Reject events older than 5 minutes (replay protection).
  const age = Math.abs(Date.now() / 1000 - Number(ts));
  if (age > 300) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${ts}.${rawBody}`)
    .digest("hex");

  // timingSafeEqual to mitigate timing attacks.
  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(sig, "hex"),
  );
}

import hashlib
import hmac
import time


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

    Header format: `t=<timestamp>,v1=<hex_hmac>`
    Rejects events older than 5 minutes (replay protection).
    """
    parts = dict(p.split("=") for p in signature_header.split(","))
    ts = parts.get("t")
    sig = parts.get("v1")
    if not ts or not sig:
        return False

    if abs(time.time() - int(ts)) > 300:
        return False

    expected = hmac.new(
        secret.encode("utf-8"),
        f"{ts}.{raw_body.decode('utf-8')}".encode("utf-8"),
        hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(expected, sig)

Retry policy

If your endpoint responds anything other than HTTP 2xx (timeout, 5xx, connection refused), we retry on exponential backoff. Total 6 attempts over ~9 hours. After 6, the event is marked `failed` in your webhook dashboard and an alert email is sent.

If you want to manually replay a failed event, the webhook dashboard offers a 'Re-deliver' button on each failed delivery — available for 7 days after the final failure.

Test without sending a real envelope

The `/v1/webhooks/test` endpoint accepts a URL and an event type, and POSTs a fake payload signed exactly like a real one. Perfect for validating your handler in CI or during local development (with ngrok or similar).

# Trigger a test webhook to your endpoint
curl -X POST https://api.certyneo.com/v1/webhooks/test \
  -H "Authorization: Bearer $CERTYNEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event": "envelope.completed", "url": "https://your.app/webhooks/certyneo"}'

Go further

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