Webhook-Payloads, Signatur und Wiederholungen
Ein Webhook ist ein HTTP-Aufruf, mit dem ein System ein anderes über ein Ereignis informiert. Die Seite zeigt JSON-Nutzlasten für Ereignisse wie rechnung.bezahlt, einen Verbindungstest, einen Signatur-Header mit HMAC-SHA-256, typische Zustellungs-Header, die Antwort des Empfängers und einen Wiederholungsplan. Schemata und Ereignisse sind erfunden, der Schlüssel ist ein Platzhalter.
9 Varianten auf einer Seite, jede mit eigenem Kopier- oder Download-Knopf. Darunter: 3× Fiktiv, 1× Reservierter Bereich, 2× Absichtlich ungültig.
Webhook-Nutzlast: rechnung.bezahlt (erfunden)Fiktiv
{ "id": "evt_0001", "typ": "rechnung.bezahlt", …Eigenes Schema mit Umschlag aus id, typ, erstellt, daten; nicht das Format eines realen Anbieters.
Webhook-Nutzlast: bestellung.angelegt (erfunden)Reservierter Bereich
{ "id": "evt_0002", "typ": "bestellung.angelegt", …Erfundene Bestellung; nicht das Schema eines realen Anbieters.
Webhook-Nutzlast: abo.gekuendigt (erfunden)Fiktiv
{ "id": "evt_0003", "typ": "abo.gekuendigt", …Erfundenes Schema.
Webhook-Nutzlast für einen VerbindungstestFiktiv
{"ereignis":"test","id":"evt_0001"}Wird für den Signatur-Eintrag unten verwendet.
Webhook-Signatur-Header (HMAC-SHA-256, berechnet)Absichtlich ungültig
X-Signature: sha256=d76a7f45acf12ccbda506b4547dd27cb085eec37db34956328699981f4d0ea9b
HMAC-SHA-256 über {"ereignis":"test","id":"evt_0001"} mit dem Platzhalter-Schlüssel whsec_ plus 24 X (beim Erstellen nachgerechnet).
Typische Header einer Webhook-ZustellungAbsichtlich ungültig
POST /webhook HTTP/1.1 Host: example.com Content-Type: application/json …
Signatur ist ein Platzhalter.
Antwort des Empfängers: 200 OK
HTTP/1.1 200 OK Content-Length: 0
Empfänger sollen schnell mit 2xx antworten und danach verarbeiten.
Wiederholungsplan für Webhooks (Beispiel)
1. Versuch: sofort 2. Versuch: nach 1 Minute 3. Versuch: nach 5 Minuten …
Beispiel für exponentielles Zurückweichen; Zeiten frei gewählt.
Hinweis zur Idempotenz von Webhooks
Zustellung mindestens einmal: dieselbe Ereignis-ID (id) kann mehrfach ankommen und muss einmalig verarbeitet werden.
Gängige Praxis bei at-least-once-Zustellung.