Webhooks in Produktion betreiben

Der Webhooks-Bereich behandelt die Grundlagen; dies ist die Checkliste für die Produktion.

Der Vertrag

• Die Zustellung erfolgt mindestens einmal und ungeordnet. Dedupliziere anhand der Event-id und behandle data.object als aktuellen Zustand, nicht als Diff.
• Antworte schnell mit 2xx (in eine Warteschlange stellen, dann verarbeiten). Das Timeout beträgt 10 s.
• Wiederholungen: 1 min → 5 min → 30 min → 2 h → 12 h, danach gilt die Zustellung als fehlgeschlagen.
• Nach 20 aufeinanderfolgenden Fehlschlägen wird der Endpoint automatisch deaktiviert. Du siehst das unter Einstellungen → Entwickler → Webhooks (nach der Behebung wieder aktivieren).

Jede Zustellung prüfen

Prüfe X-Nembol-Signature (t=…,v1=…, HMAC-SHA256 von <t>.<raw body> mit dem Secret deines Endpoints). Den vollständigen Code findest du unter Signaturen prüfen. Während einer Rotation des Secrets werden 24 h lang sowohl die alte als auch die neue Signatur gesendet.

Stolperfallen

• Verwende den rohen Request-Body für den HMAC. Jede erneute Serialisierung macht die Signatur ungültig.
• Ein Zeitfenster verpasst? Fehlgeschlagene Zustellungen lassen sich im Dashboard erneut senden (Webhooks → Zustellungen → Erneut zustellen), und GET /events ist dein Backfill: Events werden 30 Tage aufbewahrt.
• Endpoints müssen HTTPS auf einem öffentlichen Host verwenden: ein Domainname (keine IP-Adresse, kein localhost, *.localhost, *.local oder *.internal), der zu einer öffentlichen Adresse aufgelöst wird. Ein Name, der zu einer privaten oder internen Adresse aufgelöst wird, wird bei der Zustellung abgelehnt (der Versuch schlägt fehl).
• Zuerst testen: Test-Event senden im Dashboard schickt ein signiertes Dummy-Event an deinen Endpoint. Richte die Signaturprüfung ein, bevor du live gehst.

Zuletzt aktualisiert am 20. Oktober 2026