Webhooks modtage signatur begivenheder i realtid

Laddens format

Alle leveringer deler det samme top-level JSON-skema: `event`, `data` og `timestamp`. Begivenhedsnavnet gentages også i `X-Certyneo-Event`-headeren, hvilket tillader routing, før kroppen engang parses. Indholdet af `data` varierer efter begivenhed, men er altid et fladt objekt af simple værdier — aldrig et array eller indlejret objekt. Her er en fuldstændig `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 er et forhåndssignet link, der er gyldigt i 7 dage fra begivenheden: det undgår et second autentificeret opkald for at hente PDF'en. Det er fraværende — og ikke null — hvis forhåndssigneringen mislykkedes, eller på en QES-konvolut udfyldt uden lagret dokument; gå derefter tilbage til GET /v1/envelopes/id/signed-document, som er den ultimative kilde til sandhed. Vær også opmærksom på manuel genafspilning fra dead-letter køen mere end 7 dage efter begivenheden: linket i payload er udløbet, API-slutpunktet ikke.

HMAC-signaturen beregnes på den rå krop som sendt ikke ændre mellemrum, JSON-re-parsing ændrer ofte nøglernes rækkefølge og bryder verifikationen.

Kontroller HMAC-signaturen

Hver anmodning er signeret med dit webhook-hemmelighed (vist kun én gang ved oprettelse af abonnementet). Signaturen transmitteres i headerfeltet `X-Certyneo-Signature`: det er HMAC-SHA256 af det rå anmodningsindhold, kodet i hexadecimal, uden præfiks eller tidsstempel. Verificer ALTID signaturen før behandling af payload — uden dette trin kan hvem som helst forfalske en begivenhed og kalde dit 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-politik

Hvis dit endpoint tager for lang tid at svare, nægter forbindelsen eller returnerer en 5xx (eller en 429), forsøger vi igen efter eksponentiel backoff: 5 forsøg i alt over cirka 1 t 20 min. Efter det femte forsøg går begivenheden til dead-letter queue — den kan ses og afspilles igen fra dit dashboard, men bliver ikke automatisk forsøgt igen. En eksplicit nægtelse (401, 403, 404, 410, 422…) bliver derimod aldrig forsøgt igen: svaret ville ikke ændres, begivenheden går direkte til dead-letter queue.

De angivne tidsfrister er minimumskrav: retry-scanningen styres af en cron, så et forsøg kan derfor starte lidt efter det teoretiske tidspunkt. Opgive begivenheder vises i Webhooks → Fejl, med en manuel afspilningsknap uden begrænsning på opbevaringsduration. Et endpoint der efterfølges af fem endelige fejl — eller som returnerer 404 / 410 — deaktiveres automatisk, og du får besked pr. email: genaktiver det når det er rettet, tælleren starter forfra (enhver vellykket levering nulstiller det også).

Test uden at sende en ægte konvolut

Opret først et abonnement — svaret indeholder det `hemmelighed`, der er nødvendigt til HMAC-verifikation, vist kun én gang. Fra Indstillinger → Webhooks sender knappen « Test » derefter en signeret POST nøjagtigt som en ægte levering og viser dig det rå svar fra serveren: det er den hurtigste måde at validere din handler på, lokalt via ngrok eller i 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"]
  }'

URL'en skal være offentligt tilgængelig via HTTPS: en privat adresse eller localhost afvises af SSRF-beskyttelsen på oprettelsestidspunktet for abonnementet.

Abonnementer er isoleret efter miljø, ligesom nøgler: en webhook, der er oprettet med en sk_test_-nøgle, modtager kun begivenheder fra testkonvolutter, en webhook, der er oprettet med en sk_live_-nøgle, modtager kun begivenheder fra rigtige konvolutter. En testkonvolut når derfor aldrig din produktions-URL, og hver payload angiver "sandbox" (true eller false).

For at gå videre

• Udviklerhub
• E-signatur API
• Indfødte integrationer
• Sikkerhedsside
• Planer og priser