Zustellverhalten

Die Standard-Nutzlast, das Zeitlimit von 5 Sekunden, warum es keine Wiederholungsversuche gibt und was die einzelnen Zustellstatus bedeuten.

Die Webhook-Zustellung ist bewusst einfach gehalten, und diese Einfachheit hat Folgen für Ihren Empfänger: ein HTTP-Versuch, fünf Sekunden, keine Wiederholung. Lesen Sie diese Seite, bevor Sie entscheiden, wie viel Arbeit Ihr Handler direkt ausführt.

Die Standard-Payload

Jedes Ereignis außer listing.submission wird mit derselben Struktur auf oberster Ebene zugestellt, wobei die ereignisspezifischen Felder unter data verschachtelt sind.

{  "event": "connection.location_connected",  "timestamp": "2026-08-25T14:32:10Z",  "account_id": 11073,  "location_id": "279381",  "data": {    "platform": "google",    "connected_account_id": "ba03bc4b-9f8c-4d3b-8e93-9628034c63cc"  }}

Optionale Felder innerhalb von data werden bei leerem Wert weggelassen, statt als null gesendet zu werden. Programmieren Sie defensiv: Behandeln Sie einen fehlenden Schlüssel genauso wie ein explizites null, und gehen Sie niemals davon aus, dass ein als optional dokumentierter Schlüssel vorhanden ist.

Zwei Ausnahmen

Das Zeitbudget von 5 Sekunden

Jede Zustellung besteht aus einem einzelnen POST mit einem Verbindungs-Timeout von 5 Sekunden und einem Lese-Timeout von 5 Sekunden. Wenn Ihr Endpunkt nicht rechtzeitig geantwortet hat, wird der Versuch abgebrochen und als timeout protokolliert.

Dieses Zeitbudget gilt für Ihren gesamten Handler. Nur der folgende Ablauf ist sicher:

1. Prüfen Sie die Signatur.
2. Speichern Sie die Payload dauerhaft: in einer Warteschlange, einer Tabelle oder einem Protokoll.
3. Geben Sie 200 zurück.

Alles Weitere (Datenanreicherung, Verteilung an mehrere Empfänger, Rückaufrufe an die REST API und alle Zugriffe auf Drittanbieter) gehört in die Verarbeitung nach der Warteschlange.

Es gibt keine Wiederholungsversuche

Eine Zustellung wird genau einmal versucht. Es gibt weder Backoff noch eine Warteschlange für Wiederholungsversuche oder eine Dead-Letter-Warteschlange. Wenn Ihr Endpunkt zwei Minuten lang nicht erreichbar ist, gehen die in diesen zwei Minuten ausgelösten Ereignisse verloren. Sie werden nicht später zugestellt.

Zwei Folgen sind dabei ausdrücklich zu beachten:

• Weiterleitungen werden nicht verfolgt. Weiterleitungen sind vollständig deaktiviert, sodass ein 301 oder 302 von Ihrem Endpunkt als fehlgeschlagene Zustellung protokolliert wird, statt die Zustellung an einer zweiten URL fortzusetzen. Konfigurieren Sie die endgültige URL als Ihre Webhook-URL. Achten Sie auf Weiterleitungen von der Domain ohne Subdomain zu www sowie auf Weiterleitungen zum Anhängen eines abschließenden Schrägstrichs, die viele Webserver standardmäßig hinzufügen.
• Nur ein 2xx gilt als zugestellt. 3xx, 4xx und 5xx werden alle als Fehler protokolliert.

Duplikate und Reihenfolge

• Sie können dasselbe Ereignis zweimal und dieselbe id für zwei verschiedene Änderungen erhalten. Die Kennungen in data (eine Interaktions-id, eine Beitragsobjekt-id, eine id eines verbundenen Kontos) bezeichnen die Ressource, nicht die Änderung. interaction.review wird bei jeder Änderung der Bewertung erneut mit derselben Interaktions-id ausgelöst, und keine Nutzlast enthält eine Version oder ein updated-at-Feld. Ein Handler, der Ereignisse anhand von id + event dauerhaft unterdrückt, verwirft daher unbemerkt tatsächliche Änderungen. Erkennen Sie stattdessen exakte Duplikate: Berechnen Sie einen Hash der unverarbeiteten Bytes des Bodys und ignorieren Sie Wiederholungen desselben Hashs innerhalb eines kurzen, begrenzten Zeitfensters (Minuten, nicht dauerhaft). Ein anderer Body mit derselben id ist eine neue Änderung, kein Duplikat. Lesen Sie anschließend die Ressource erneut über die REST API aus und betrachten Sie das Ergebnis als maßgeblich; verwenden Sie die Ressourcen-id als Schlüssel für den Schreibvorgang, statt ihn zu überspringen.
• Die Reihenfolge ist nicht garantiert, und timestamp ändert daran nichts. Ereignisse stammen aus mehreren unabhängigen Verarbeitungswegen und werden bei Eingang zugestellt. Daher kann ein local_post.published vor dem local_post.created eintreffen, das Sie zuerst erwartet haben. Ordnen Sie zwei Änderungen an derselben Ressource nicht anhand von timestamp: Dieser Zeitstempel wird beim Erstellen der Zustellung gesetzt, nicht zum Zeitpunkt der Änderung, und die Nutzlast enthält weder eine Version noch eine Sequenznummer. Wenn die Reihenfolge relevant ist, lesen Sie die Ressource erneut aus und verwenden Sie das Ergebnis der API.
• profile.updated wird durch Debouncing begrenzt: auf eine Zustellung pro Standort alle 60 Sekunden, jeweils zu Beginn des Zeitfensters. Dabei werden Änderungen tatsächlich zusammengefasst und nicht verzögert: Die erste Änderung öffnet das Zeitfenster und wird zugestellt, jede Änderung innerhalb des Zeitfensters wird verworfen und trifft nie ein, und changed_fields beschreibt nur die Änderung, die das Zeitfenster geöffnet hat. Das Ereignis erreicht Sie daher zu Beginn des Zeitfensters, sodass ein bei seinem Eingang ausgelöstes erneutes Auslesen immer nur diese erste Änderung erfassen kann. Planen Sie ein zweites Auslesen nach Ende des Zeitfensters, frühestens 60 Sekunden nach dem Ereignis, und gleichen Sie Standorte zusätzlich zeitgesteuert ab, da auch die Benachrichtigung selbst verloren gehen kann: ein Versuch, keine Wiederholung. Für nichts anderes wird Debouncing angewendet.

Wiederherstellung nach einem verpassten Ereignis

Es gibt weder einen erneuten Zustellversuch noch eine erneute Auslieferung vergangener Ereignisse. Daher benötigen Sie für jede Ereignisfamilie eine maßgebliche Leseabfrage, auf die Sie zurückgreifen können. Führen Sie den Abgleich nach einem Zeitplan durch, nicht nur, wenn etwas falsch erscheint.

Zustellergebnisse

Jeder Versuch wird mit einem Status protokolliert, auch wenn dabei keine Anfrage gesendet wird. Dies sind die exakten Zeichenfolgen.

Checkliste für den Empfänger

• Prüfen Sie bei jeder Anfrage die Signatur; geben Sie bei einer Abweichung 401 zurück und verarbeiten Sie nichts.
• Berechnen Sie den Hash aus den unveränderten Bytes des Anfragebodys, niemals aus einem erneut serialisierten Objekt.
• Geben Sie 2xx deutlich vor Ablauf von 5 Sekunden zurück; stellen Sie die Verarbeitung in eine Warteschlange.
• Verwenden Sie bei jedem Schreibvorgang des Handlers die IDs in data als Schlüssel, damit eine Wiederholung dasselbe Ergebnis liefert, aber gehen Sie bei einer wiederholten ID niemals davon aus, dass nichts zu tun ist.
• Leiten Sie aus der Empfangsreihenfolge keine Reihenfolge ab und sortieren Sie nicht nach timestamp.
• Normalisieren Sie location_id beim Eingang zu einer Zeichenfolge.
• Ignorieren Sie unbekannte Werte für event und geben Sie trotzdem 200 zurück.
• Stellen Sie die Webhook-URL als endgültige URL ohne Weiterleitungen bereit.
• Gleichen Sie die Daten regelmäßig mit der REST API ab; es gibt keine Wiederholungsversuche, die dies auffangen.