Webhooks — ontvang handtekeningsgebeurtenissen in realtime

Payload-indeling

Alle gebeurtenissen delen hetzelfde top-level JSON-schema: `event`, `envelope_id`, `occurred_at`, `data`. De inhoud van `data` varieert per gebeurtenis (velden gedocumenteerd per gebeurtenis in de API-referentie). Hier volgt een volledig voorbeeld van `envelope.completed`.

{
  "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"
  }
}

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 aanvraag wordt ondertekend met uw webhook-geheim (eenmalig zichtbaar bij aanmaking in het dashboard, daarna versleuteld in rust). De handtekening wordt doorgegeven in de `Certyneo-Signature`-header in het formaat `t=<timestamp>,v1=<hex_hmac>`. 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 {
  // 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)

Beleid voor opnieuw proberen

Als uw eindpunt iets anders antwoordt dan HTTP 2xx (timeout, 5xx, verbinding geweigerd), doen we een poging opnieuw volgens exponentieel backoff. In totaal 6 pogingen gedurende ~9 uur. Na de 6e poging wordt de gebeurtenis als `failed` gemarkeerd in uw webhook-dashboard en wordt een waarschuwings-e-mail verzonden.

Als u een gemiste gebeurtenis handmatig opnieuw wilt verzenden, biedt het webhook-dashboard een knop « Re-deliver » voor elke mislukte aflevering — beschikbaar gedurende 7 dagen na de definitieve fout.

Testen zonder een echte envelop te verzenden

Het eindpunt `/v1/webhooks/test` accepteert een URL en een gebeurtenistype, en POSTet een fictieve payload die exact zoals een echte is ondertekend. Ideaal om uw handler in continue integratie of tijdens lokale ontwikkeling te valideren (met ngrok of gelijkwaardig).

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

Verder verkennen

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