Webhooks im Überblick

Wie die Listings API Kontoereignisse an Ihren Server sendet, welche Ereignisse es gibt und welche fünf Prüfungen jede Zustellung durchlaufen muss.

Eine API regelmäßig abzufragen, um Änderungen festzustellen, ist aufwendig und liefert die Information immer etwas verzögert. Webhooks kehren diesen Ablauf um: Wenn in Ihrem Konto etwas passiert (eine Bewertung eingeht, ein Standort bearbeitet wird, ein Google Business-Beitrag veröffentlicht wird), sendet die Listings API innerhalb von Sekunden eine HTTP-Anfrage mit der Methode POST und einem JSON-Body an eine URL, die Sie kontrollieren.

Es gibt eine Webhook-URL pro Konto und keine Abonnements für einzelne Ereignisse. Wenn Webhooks für Ihr Konto aktiviert sind und Ihr Endpunkt verifiziert ist, wird jedes auf dieser Seite aufgeführte Ereignis an diese eine URL zugestellt. Unterscheiden Sie anhand des Felds event zwischen den Ereignissen und ignorieren Sie, was Sie nicht benötigen.

Der Zustellungsablauf

Welche Ereignisse Sie empfangen können

18 Ereignisse in sechs Gruppen. Jedes entspricht einer Ressource, die Sie bereits über die REST API verwalten. Der Webhook teilt Ihnen also mit, wann etwas passiert, und der Endpunkt zeigt Ihnen, was passiert ist.

Vollständige Feldtabellen und Beispiel-Payloads finden Sie in der Ereignisreferenz.

Nicht abgedeckt

Die Plattform erzeugt weitere Ereignisgruppen, die von der Listings API weder dokumentiert noch unterstützt werden, da es hier keinen veröffentlichten REST-Endpunkt dafür gibt. Sie werden aufgeführt, damit nicht der Eindruck entsteht, sie seien versehentlich ausgelassen worden:

• Bewertungskampagnen: campaign.*
• Rankings: rankings.*
• Beiträge und beworbene Beiträge in Social: social_post.*
• Verbindungen in Social: social_connection.*
• KI-Beitragsideen: idea.*, idea_series.*, idea_pipeline.*, idea_image.*
• Inhaberschaft bei Google Business Profile: gbp_ownership.*

Zwei Einschränkungen, die Sie vor der Implementierung kennen sollten

Prüfschritte vor der Zustellung

Die Zustellung hängt von fünf Bedingungen ab, die in dieser Reihenfolge geprüft werden. Der erste fehlgeschlagene Prüfschritt stoppt die Zustellung; spätere Prüfschritte werden nicht mehr erreicht.

Tarife und Limits

Webhooks sind in jedem Tarif als Berechtigung enthalten: Launch, Growth und Enterprise. Eine Testphase läuft mit dem von Ihnen gewählten Tarif, sodass Testkonten vom ersten Tag an Webhooks mit den Obergrenzen dieses Tarifs nutzen können. Die Berechtigung ist an Ihren Tarif gebunden und wird daher im Rahmen eines Tarifwechsels erteilt oder entzogen, nicht sofort: Rechnen Sie damit, dass sie beim nächsten Tarifwechsel oder bei der Synchronisierung im Rahmen der Registrierung wirksam wird, nicht in dem Moment, in dem Sie auf Upgrade klicken. Die Seite Webhooks im Dashboard zeigt Ihre aktuell geltende Berechtigung und Ihre Obergrenzen.

Für Zustellungen gelten außerdem eine Obergrenze pro Minute und eine Obergrenze pro Tag, die beide von Ihrem Tarif abhängen.

Die Webhook-Obergrenzen entsprechen den Limits für API-Anfragen Ihres Tarifs: Das Kontingent für Ereignisse, die wir Ihnen senden, ist genauso groß wie das Kontingent für Anfragen, die Sie uns senden.

Eine Obergrenze gilt für Ihr Konto erst, nachdem die Limits Ihres Tarifs mit dem Zustellungssystem synchronisiert wurden. Bis dahin gibt es keine Obergrenze, die geprüft werden könnte. Daher wird weder die Nutzung gezählt noch ein Ereignis verworfen. Bei einem neu angelegten Konto können Zustellungen deshalb zunächst ohne Zählung erfolgen, bevor die Obergrenze des Tarifs greift. Werten Sie das Ausbleiben von rate_limited nicht als Beleg dafür, dass Sie unter dem Limit liegen.

So funktioniert die Zählung:

• Zwei unabhängige feste Zeitfenster: eines pro Minute, eines pro Tag. Es gibt kein stündliches Webhook-Zeitfenster. (Die Begrenzung der Anfragerate ist ein separates System mit anderen Zeitfenstern; die beiden Systeme nutzen kein gemeinsames Kontingent.)
• Die Zeitfenster richten sich nach festen Kalendergrenzen, sie sind nicht gleitend: Der Minutenzähler wird zu Beginn jeder Minute zurückgesetzt, der Tageszähler zu Beginn jedes UTC-Tages.
• Bei Überschreitung wird das Ereignis verworfen. Es wird weder in eine Warteschlange aufgenommen noch verzögert oder erneut zugestellt: Im gesamten ausgehenden Zustellungsweg gibt es keine Warteschlange für Wiederholungsversuche und keinen Aufrufer, an den ein 429 zurückgegeben werden könnte. Der Versuch wird mit dem Zustellungsstatus rate_limited protokolliert, damit der Verlust sichtbar ist und nicht unbemerkt bleibt.
• Bei einem Fehler lässt die Begrenzung die Zustellung zu. Wenn die Begrenzung selbst keine Entscheidung liefern kann, wird die Zustellung ausgeführt, statt das Ereignis zu verwerfen. Durch einen fehlerhaften Zähler geht Ihnen niemals ein Ereignis verloren.

Die einzige integrierte Mengenbegrenzung auf der erzeugenden Seite ist eine Entprellung für profile.updated: höchstens eine Zustellung pro Standort innerhalb von 60 Sekunden, jeweils zu Beginn des Zeitfensters. Schnell aufeinanderfolgende Änderungen am selben Standort werden zu einem einzigen Ereignis zusammengefasst, und die empfangenen changed_fields beschreiben nur die Änderung, die das Zeitfenster ausgelöst hat. Sonst wird nichts entprellt.

Da die Zustellung zu Beginn des Zeitfensters erfolgt, erreicht sie Sie am Anfang des 60-Sekunden-Zeitfensters: Eine durch den Empfang ausgelöste erneute Abfrage erfasst nur die erste Änderung. Planen Sie nach Ablauf des Zeitfensters, frühestens 60 Sekunden nach dem Ereignis, eine zweite Abfrage ein und gleichen Sie die Standorte zusätzlich in regelmäßigen Abständen ab, da für das Ereignis selbst nur ein Zustellungsversuch ohne Wiederholung erfolgt. Siehe Wiederherstellung nach einem verpassten Ereignis.

Einrichtung

1. Richten Sie einen HTTPS-Endpunkt ein. Er muss öffentlich auflösbar sein, ein gültiges Zertifikat haben, POST akzeptieren und in weniger als 5 Sekunden mit 2xx antworten. Private und interne Adressen (Loopback, RFC-1918, Link-Local, IP-Adressen für Cloud-Metadaten) werden abgelehnt.
2. Speichern Sie Ihre Webhook-URL auf der Seite „Webhooks“ im Dashboard. Eine URL pro Konto für alle Ereignisse.
3. Generieren Sie ein Signierungsgeheimnis und speichern Sie es auf Ihrem Server. Es wird nur einmal angezeigt. Ab diesem Zeitpunkt werden Zustellungen signiert und eine Verifizierung ist erforderlich.
4. Verifizieren Sie den Endpunkt. Die Plattform sendet eine signierte Verifizierungsanfrage; Ihr Endpunkt antwortet mit einem hexadezimalen HMAC der Nonce. Bei Erfolg wird der Endpunkt als verifiziert markiert und die Zustellungen beginnen. Die genauen Anforderungen und funktionsfähigen Code finden Sie unter Signaturen und Verifizierung.
5. Verarbeiten Sie die Ereignisse. Prüfen Sie die Signatur, stellen Sie die Nutzdaten in eine Warteschlange und geben Sie 200 zurück. Führen Sie die eigentliche Verarbeitung außerhalb der Anfrageverarbeitung aus. Informationen zum Timeout, zur Beschränkung auf einen einzigen Zustellversuch und zum Umgang mit Duplikaten und der Reihenfolge finden Sie unter Zustellverhalten.

Weiterführende Informationen

• Signaturen und Verifizierung: der Header X-ListingsAPI-Signature, die Regel zum unverarbeiteten Request-Body und der Handshake.
• Zustellverhalten: die Standardnutzdaten, das Timeout von 5 Sekunden, der Grund für den Verzicht auf Wiederholungsversuche und alle Zustellstatus.
• Ereignisreferenz: alle 18 Ereignisse, Feld für Feld.