Appearance
10. Webhooks
Ereignisse, Signaturprüfung, Retry und Secret-Rotation.
Ziel
Eure Anwendung empfängt Zustellereignisse in Echtzeit, prüft ihre Echtheit korrekt und übersteht eine Secret-Rotation ohne Unterbrechung.
Voraussetzung
Eine Webhook-URL im Kundenbereich hinterlegt (Webhooks → Erstellen). Dispatch erzeugt das Signatur-Secret automatisch — es wird nie im Formular angezeigt.
Ereignisse
Fünf Events, je Webhook einzeln abonnierbar: delivered, bounced, complained, unsubscribe.created, reply.received.
Aufruf und Body
Dispatch ruft eure URL per POST mit JSON auf:
json
{
"event": "delivered",
"message_id": 483920,
"campaign_id": 67,
"recipient": "kunde@beispiel-mandant.test",
"status": "delivered",
"bounce_code": null,
"occurred_at": "2026-09-21T09:00:07+00:00"
}Bei unsubscribe.created zusätzlich unsubscribe_method (list-unsubscribe oder link), scope und list_id.
reply.received meldet eine Mail, die jemand direkt an eine Absenderadresse geschrieben hat (nur mit eingeschalteter Antwortannahme, Kapitel 3). Sie gehört zu keiner versendeten Nachricht, deshalb fehlen message_id, campaign_id, recipient, status und bounce_code. Stattdessen enthält der Body die Antwort selbst:
json
{
"event": "reply.received",
"occurred_at": "2026-10-05T10:56:58+00:00",
"reply_id": 1,
"sending_domain": "news.beispiel-mandant.test",
"sending_identity_id": 1,
"original_recipient": "newsletter@news.beispiel-mandant.test",
"reply_to": "info@beispiel-mandant.test",
"from_email": "kunde@beispiel-empfaenger.test",
"from_name": "Erika Beispiel",
"subject": "Re: Herbstprogramm",
"message_id": "abc123@beispiel-empfaenger.test",
"in_reply_to": "nl-1@news.beispiel-mandant.test",
"body_text": "Gilt das Angebot auch für zwei Personen?",
"body_html": null,
"received_at": "2026-10-05T10:56:57+00:00"
}message_id ist hier die Message-ID der eingegangenen Mail (Text), nicht eine Dispatch-Nachrichten-ID. reply_to ist die Reply-To-Adresse der Absenderidentität, an die geschrieben wurde. Ihr könnt die Antwort damit dem richtigen Postfach zuordnen. Dieselbe Mail wird nur einmal gemeldet. Zeitangaben sind wie überall UTC.
Signaturprüfung
Zwei Header:
X-Dispatch-Event— der Ereignisname, identisch zueventim Body.X-Dispatch-Signature—hash_hmac('sha256', <roher Body>, <euer Secret>).
Prüft die Signatur gegen den rohen Request-Body (vor jedem JSON-Parsing) mit eurem gespeicherten Secret. Stimmt sie nicht überein, verwerft den Aufruf.
Retry-Verhalten
Dispatch wartet 10 Sekunden auf eine Antwort. Antwortet euer Endpunkt nicht innerhalb dieser Zeit mit einem 2xx-Status (oder ist nicht erreichbar), versucht Dispatch es bis zu 5-mal erneut, gestaffelt nach 10, 30, 60, 300 und 900 Sekunden. Jeder einzelne Versuch ist in der Zustellhistorie nachvollziehbar. Antwortet euer Endpunkt zuverlässig innerhalb der 10 Sekunden mit 2xx, ist ein Versuch ausreichend — nehmt zeitaufwendige eigene Verarbeitung deshalb aus dem Antwortpfad heraus und verarbeitet sie asynchron.
Secret-Rotation ohne Unterbrechung
Über Secret rotieren im Kundenbereich erzeugt Dispatch ein neues Secret. Für die folgenden 7 Tage bleibt zusätzlich ein dritter Header gesetzt:
X-Dispatch-Signature-Previous— dieselbe Signatur, aber mit dem alten Secret berechnet.
Akzeptiert in dieser Übergangszeit beide Signaturen (neues Secret gegen X-Dispatch-Signature, oder altes Secret gegen X-Dispatch-Signature-Previous) — so könnt ihr euren gespeicherten Secret-Wert aktualisieren, ohne dass zwischenzeitlich Aufrufe verworfen werden. Nach 7 Tagen verschwindet der -Previous-Header wieder, und nur noch das neue Secret gilt.
Ergebnis
Eure Anwendung verarbeitet Webhooks sicher signiert und übersteht eine Secret-Rotation ohne Ausfall. Weiter mit Kapitel 7 für die genaue Bedeutung von unsubscribe.created, oder mit Kapitel 13 für Troubleshooting.