Webhooks — Empfangen Sie Signaturedeignisse in Echtzeit

Payload-Format

Alle Zustellungen teilen das gleiche JSON-Schema auf oberster Ebene: `event`, `data` und `timestamp`. Der Ereignisname wird auch im Header `X-Certyneo-Event` wiederholt, was das Routing ermöglicht, bevor der Body geparst wird. Der Inhalt von `data` variiert je nach Ereignis, bleibt aber immer ein flaches Objekt mit einfachen Werten — niemals ein Array oder verschachteltes Objekt. Hier ist eine vollständige `envelope.completed` Zustellung.

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 ist ein vorsignierter Link, der 7 Tage lang gültig ist, gerechnet ab dem Ereignis: Er vermeidet einen zweiten authentifizierten Aufruf zum Abrufen des PDF. Er ist abwesend — und nicht null — wenn die Vorsignatur fehlgeschlagen ist oder bei einem QES-Umschlag ohne gespeichertes Dokument. Verwenden Sie dann GET /v1/envelopes/id/signed-document, das bleibt die maßgebliche Quelle. Achten Sie auch auf manuelle Wiederholung aus der Dead-Letter-Queue mehr als 7 Tage nach dem Ereignis: Der Link im Payload ist abgelaufen, der API-Endpoint nicht.

Die Payload ist UTF-8 codiert, ohne BOM. Die HMAC-Signatur wird auf dem rohen Body berechnet, wie er gesendet wird — verändern Sie keine Leerzeichen, das erneute JSON-Parsing ändert häufig die Reihenfolge der Schlüssel und bricht die Verifizierung.

HMAC-Signatur verifizieren

Jede Anfrage wird mit Ihrem Webhook-Secret signiert (wird bei der Erstellung des Abonnements nur einmal angezeigt). Die Signatur wird im Header `X-Certyneo-Signature` übermittelt: Dies ist der HMAC-SHA256 des rohen Request-Body, hexadezimal kodiert, ohne Präfix oder Zeitstempel. IMMER die Signatur vor der Verarbeitung des Payloads überprüfen — ohne diesen Schritt kann jeder ein Ereignis fälschen und Ihren Endpoint aufrufen.

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-Richtlinie

Wenn Ihr Endpoint zu lange zum Antworten braucht, die Verbindung ablehnt oder einen 5xx-Code (oder 429) zurückgibt, versuchen wir es nach einem exponentiellen Backoff erneut: 5 Versuche insgesamt über etwa 1 h 20. Nach dem fünften Versuch wird das Ereignis in eine Dead-Letter-Queue verschoben – sie ist einsehbar und kann von Ihrem Dashboard aus erneut abgespielt werden, wird aber nicht mehr automatisch erneut versucht. Eine ausdrückliche Ablehnung (401, 403, 404, 410, 422…) wird hingegen nie erneut versucht: die Antwort würde sich nicht ändern, das Ereignis geht direkt in die Dead-Letter-Queue.

Die angegebenen Verzögerungen sind Mindestwerte: Der Retry-Scan wird durch einen Cron-Job zeitgesteuert, daher kann ein Versuch leicht nach der theoretischen Zeit gestartet werden. Aufgegebene Ereignisse werden in Webhooks → Fehler aufgelistet, mit einer manuellen Replay-Schaltfläche und ohne Aufbewahrungsfristbeschränkung. Ein Endpoint, der fünf endgültige Fehler hintereinander hat – oder der 404 / 410 antwortet – wird automatisch deaktiviert, und Sie werden per E-Mail benachrichtigt: reaktivieren Sie ihn nach der Korrektur, der Zähler setzt sich auf Null zurück (jede erfolgreiche Lieferung setzt ihn auch auf Null zurück).

Testen ohne echte Envelope zu versenden

Erstellen Sie zunächst ein Abonnement — die Antwort enthält das `secret`, das für die HMAC-Verifizierung erforderlich ist und nur einmal angezeigt wird. Über Einstellungen → Webhooks sendet die Schaltfläche «Testen» dann einen signierten POST genauso wie eine echte Zustellung und zeigt Ihnen die rohe Antwort Ihres Servers an: Das ist die schnellste Möglichkeit, Ihren Handler lokal über ngrok oder in einer Continuous-Integration zu validieren.

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

Die URL muss öffentlich über HTTPS erreichbar sein: Eine private Adresse oder localhost wird durch den SSRF-Schutz zum Zeitpunkt der Abonnementserstellung abgelehnt.

Abonnements sind wie die Schlüssel nach Umgebung getrennt: Ein mit einem sk_test_-Schlüssel erstellter Webhook empfängt nur die Ereignisse von Testumschlägen, ein mit einem sk_live_-Schlüssel erstellter nur die echter Umschläge. Ein Testumschlag erreicht Ihre Produktions-URL also nie, und jede Payload gibt „sandbox“ an (true oder false).

Weitere Informationen

• Entwickler-Hub
• E-Signatur-API
• Native Integrationen
• Sicherheitsseite
• Pläne und Preise