Kurze Antwort
Um Zustellberichte per Webhook zu empfangen, stellen Sie einen HTTPS-Endpunkt bereit, der POST-Anfragen annimmt, und registrieren dessen URL bei Ihrem Messaging-Anbieter. Speichern Sie jedes Ereignis, antworten Sie schnell mit einem 2xx-Status und verarbeiten Sie es asynchron. Ordnen Sie Ereignisse per Message-ID Ihren Datensätzen zu, entfernen Sie Duplikate und lassen Sie nie einen verspäteten Status einen finalen überschreiben.
Endpunkt einrichten
Während der Entwicklung gibt ein Tunnel einem lokalen Server eine öffentliche HTTPS-URL.
- Stellen Sie einen HTTPS-Endpunkt bereit, der POST-Anfragen mit JSON-Body annimmt.
- Geben Sie die URL an Ihren Anbieter weiter, damit sie im richtigen Konto oder Unterkonto hinterlegt wird.
- Senden Sie eine Testnachricht an Ihre eigene Nummer und protokollieren Sie den unveränderten Ereignis-Body.
- Ordnen Sie die benötigten Felder anhand echter Ereignisse zu, nicht anhand vermuteter Feldnamen.
- Bewahren Sie Beispiel-Payloads für jeden genutzten Kanal als Test-Fixtures auf.
Welche Status erhalten Sie?
Anbieter übersetzen Berichte von Netzbetreibern und Kanälen in eigene Statusnamen. Die folgende vereinheitlichte Liste verwendet OmniChannels.ai für SMS, WhatsApp und andere Kanäle.
| Status | Bedeutung | Final? |
|---|---|---|
| SUBMITTED | Angenommen und in der Warteschlange | Nein |
| SENT | An Netzbetreiber oder Kanal übergeben | Nein |
| DELIVERED | Auf dem Gerät bestätigt | Meist; READ kann folgen |
| READ | Geöffnet, bei Kanälen mit Lesebestätigung | Ja |
| FAILED | Nicht zugestellt, mit Grund, sofern verfügbar | Ja |
| REJECTED | Abgelehnt, etwa wegen einer nicht registrierten Absenderkennung | Ja |
So wird der Handler zuverlässig
- Speichern Sie den unveränderten Body und antworten Sie dann mit 2xx. Schlägt das Speichern fehl, antworten Sie mit 5xx, damit das Ereignis erneut gesendet werden kann.
- Erledigen Sie die eigentliche Arbeit in einer Queue oder einem Worker, nicht vor der Antwort.
- Entfernen Sie Duplikate anhand der Message-ID; derselbe Status kann zweimal ankommen.
- Ordnen Sie Status nach Rang, damit ein verspätetes SENT nie ein DELIVERED überschreibt.
- Akzeptieren Sie unbekannte Statuswerte, statt einen Fehler auszulösen.
- Senden Sie aus dem Webhook-Handler heraus niemals eine Nachricht erneut.
Absichern und verpasste Berichte nachholen
Akzeptieren Sie nur HTTPS, verwenden Sie einen langen, nicht erratbaren Pfad, validieren Sie die Struktur des Bodys und bestätigen Sie den Zustand vor unumkehrbaren Aktionen wie Erstattungen mit einer Statusabfrage. War Ihr Endpunkt ausgefallen, bitten Sie den Anbieter, die Berichte für den Zeitraum erneut zu senden, oder lesen Sie die Status über seine Reporting-Endpunkte aus.
Über SMPP kommen Zustellberichte als deliver_sm im Bind an statt per Webhook. Manche Netzbetreiber liefern Berichte verspätet oder gar nicht; werten Sie sie daher als starkes Indiz, nicht als Beweis, dass gelesen wurde.