Webhooks få signaturhändelser i realtid

Payloadformat

Alla leveranser delar samma JSON-schema på högsta nivå: `event`, `data` och `timestamp`. Händelsens namn upprepas också i headern `X-Certyneo-Event`, vilket gör att man kan dirigera innan man ens tolkar kroppen. Innehållet i `data` varierar beroende på händelse, men förblir alltid ett platt objekt med enkla värden — aldrig en matris eller ett kapslat objekt. Här är en komplett `envelope.completed` leverans.

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 är en försignerad länk giltig 7 dagar från händelsen: den undviker ett andra autentiserat samtal för att hämta PDF:en. Den är frånvarande — och inte null — om försigneringen misslyckades, eller på ett QES-kuvert slutfört utan lagrat dokument; gå sedan tillbaka till GET /v1/envelopes/id/signed-document, som förblir sanningens källa. Var också försiktig med manuell omspelning från dead-letter queue mer än 7 dagar efter händelsen: länken i nyttolasten är utgången, API:et är inte det.

Payload är kodad UTF-8, utan BOM. HMAC-signaturen beräknas på den råa kroppen som skickas ändra inte med tomrummen, JSON-reparsering ändrar ofta ordningen på nycklarna och bryter verifieringen.

Kontrollera HMAC-signaturen

Varje begäran är signerad med din webhook-hemlighet (visad endast en gång när prenumerationen skapas). Signaturen överförs i rubriken `X-Certyneo-Signature`: det är HMAC-SHA256 för begärans råa brödtext, kodad i hexadecimalt, utan prefix eller tidsstämpel. Verifiera ALLTID signaturen innan du behandlar nyttolasten — utan detta steg kan vem som helst förfalska en händelse och anropa din 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)

Återförsökspolicy

Om din endpoint tar för lång tid att svara, vägrar anslutningen eller returnerar ett 5xx (eller ett 429), försöker vi igen enligt exponentiell backoff: 5 försök totalt, under cirka 1 h 20. Efter det femte försöket går händelsen till dead-letter queue — den kan visas och spelas upp igen från din instrumentpanel, men försöks inte automatiskt igen. Ett explicit vägran (401, 403, 404, 410, 422…) försöks däremot aldrig igen: svaret skulle inte förändras, händelsen går direkt till dead-letter queue.

De angivna tiderna är minimier: omförsökssökningen styrs av ett cron-jobb, så ett försök kan därför starta något senare än den teoretiska tiden. Övergivna händelser visas i Webhooks → Fel, med en knapp för manuell omspelning och utan gräns för lagringstid. En endpoint som får fem definitiva fel i rad — eller som svarar 404/410 — inaktiveras automatiskt, och du meddelas per e-post: återaktivera den när den är åtgärdad, räknaren börjar om från noll (varje lyckad leverans återställer den också till noll).

Provning utan att skicka ett riktigt kuvert

Skapa först en prenumeration — svaret innehåller `secret` som behövs för HMAC-verifikation, visad endast en gång. Från Inställningar → Webhooks skickar knappen "Testa" sedan ett signerat POST exakt som en verklig leverans och visar dig det råa svaret från din server: det är det snabbaste sättet att validera din handler, 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 måste vara offentligt nåbar via HTTPS: en privat adress eller localhost avvisas av SSRF-skyddet när prenumerationen skapas.

Prenumerationer är isolerade per miljö, precis som nycklar: en webhook skapad med en sk_test_-nyckel mottar endast händelser från testkuvert, en webhook skapad med en sk_live_-nyckel mottar endast händelser från riktiga kuvert. Ett testkuvert når därför aldrig din produktions-URL, och varje nyttolast anger "sandbox" (true eller false).

För att gå vidare

• Utvecklare Hub
• E-signatur API
• Inhemsk integration
• Säkerhetssida
• Planer och priser