Listings APIListings API
Get API keySign in

Webhooks overview

How the Listings API pushes account events to your server, which events exist, and the five gates every delivery has to clear.

Polling an API to find out that something changed is expensive and always a little late. Webhooks invert it: when something happens on your account — a review arrives, a location is edited, a Google Business post goes live — the Listings API sends an HTTP POST with a JSON body to a URL you control, within seconds.

There is one webhooks URL per account and no per-event subscription. If webhooks are enabled for your account and your endpoint is verified, every event listed on this page is delivered to that one URL. Branch on the event field and ignore what you don't need.

The delivery pipeline

Every event walks the same path. The five gates are checked in order, and any one of them failing means no HTTP request is made at all — though the attempt is still recorded.

What you can receive

Eighteen events across six families. Each one maps to a resource you already manage through the REST API, so the webhook tells you when and the endpoint tells you what.

FamilyEventsRelated REST resource
listing.submission1Listings
profile.*3 — created, updated, deletedLocations
connection.*6 — connected, disconnected, reauth, inaccessible, 2 × Google verificationConnected Accounts
interaction.*2 — review, responseReviews
local_post.*4 — created, published, rejected, deletedPosts
review_analytics.*2 — daily and weekly snapshotAnalytics

Full field tables and example payloads live in the event reference.

Not in scope

The platform emits other event families that the Listings API does not document or support, because they have no published REST surface here. They are listed so nothing looks accidentally missing:

  • Review campaigns — campaign.*
  • Rankings — rankings.*
  • Social posts and boosts — social_post.*
  • Social connections — social_connection.*
  • AI post ideas — idea.*, idea_series.*, idea_pipeline.*, idea_image.*
  • Google Business Profile ownership — gbp_ownership.*

Two caveats worth reading before you build

Delivery gates

Delivery is gated on five things, checked in that order. The first gate that fails stops the delivery; later gates are never reached.

#GateIf it fails
1Your plan includes webhooks. An entitlement on the account.Nothing is recorded. The event is simply not routed to you.
2A webhooks URL is configured on the account.Nothing is recorded.
3Endpoint verification has passed — only enforced once a signing secret exists.Recorded as endpoint_unverified.
4The URL resolves to a public address (HTTPS, publicly-resolvable host).Recorded as blocked_url.
5You are inside your plan's webhook limit.Recorded as rate_limited. The event is dropped, not queued.

Plans and limits

Webhooks are an entitlement on paid plans — Launch, Growth and Enterprise. Trial accounts do not receive webhooks. The entitlement is attached to your plan, so it is granted or removed as part of a plan change rather than instantly: expect it to take effect on your next plan change or signup sync, not the moment you click upgrade. The dashboard's Webhooks page shows your live entitlement and caps.

Deliveries are also metered against a per-minute and a per-day cap, both scoped to your plan.

PlanPer-minutePer-day
Launch107,200
Growth5036,000
EnterpriseUnlimitedUnlimited

Webhook caps mirror your plan's API request limits: the budget for events we send you equals the budget for requests you send us.

A cap only starts applying to your account once your plan's limits have been synced to the delivery path. Until that has happened there is no cap to check, so nothing is metered and nothing is dropped — a brand-new account can therefore see unmetered delivery before it sees its plan's ceiling. Don't read an absence of rate_limited as proof you are under the limit.

How the meter behaves:

  • Two independent fixed windows — one per minute, one per day. There is no per-hour webhook window. (The request rate limiter is a different system with different windows; the two do not share a budget.)
  • Windows are calendar-aligned, not sliding: the minute counter resets on the minute boundary, the daily counter on the UTC day boundary.
  • On exceed the event is dropped. Not queued, not delayed, not retried — there is no retry queue anywhere in the outbound path, and no caller to return a 429 to. The attempt is recorded with the delivery status rate_limited so the loss is visible rather than silent.
  • The limiter fails open. If the limiter itself cannot answer, the delivery goes out rather than being dropped. You will never lose an event to a broken meter.

The only built-in volume control on the producing side is a debounce on profile.updated: at most one delivery per location per 60 seconds, on the leading edge. Rapid edits to the same location collapse into a single event, and the changed_fields you receive describe only the edit that opened the window. Nothing else is debounced.

Setting it up

  1. Stand up an HTTPS endpoint. It must be publicly resolvable with a valid certificate, accept POST, and reply 2xx in under 5 seconds. Private and internal addresses (loopback, RFC-1918, link-local, cloud metadata IPs) are refused.
  2. Save your webhooks URL on the dashboard's Webhooks page. One URL per account, all events.
  3. Generate a signing secret and store it on your server. It is shown once. From this point deliveries are signed and verification is required.
  4. Verify the endpoint. The platform sends a signed challenge; your endpoint answers with a hex HMAC of the nonce. On success the endpoint flips to verified and deliveries begin. See signatures and verification for the exact contract and working code.
  5. Handle the events. Verify the signature, enqueue the payload, return 200. Do the real work off the request path — see delivery behavior for the timeout, the single-attempt policy, and what to expect around duplicates and ordering.

Where to go next