Webhooks
Get told when something happens, instead of asking.
Webhooks send events to your server when something happens to a review, a response, a removal request, a review site connection, plan usage or billing. Use them instead of polling.
See the Webhook event catalogue for every event, when it's sent and what the payload looks like.
Immediate and batch subscriptions
You can have one subscription of each kind, each with its own URL and signing secret. Choose with delivery_kind when you create a webhook.
Immediate (delivery_kind: immediate) | Batch (delivery_kind: batch) | |
|---|---|---|
| What you receive | Each event as it happens, under its own name | One cache_invalidation per location that had new or changed reviews in the window |
| How often | As it happens | Every batch_interval_hours: 1, 2, 4, 6 or 12 hours, from midnight UTC |
| Choose events | Optional events filter (default: all immediate events) | No filter |
| Payload | full (default) or minimal (payload_mode) | Always the cache_invalidation payload |
| Good for | Reacting to replies, removals, failed posts and disconnected sites | Knowing which locations' reviews to refresh |
A common setup is a batch subscription to keep your copy of reviews fresh, plus an immediate subscription for the events you act on.
How to set one up
- Create a webhook with a
label, your HTTPSwebhook_urland adelivery_kind(plusbatch_interval_hoursfor batch). The response shows the signing secret once: store it. - Send a test event and check that your endpoint verifies the signature and replies with a
2xx. - Watch recent deliveries to see what was sent and how your endpoint answered.
If you lose the secret, show it again or rotate it.
Receiving events
Each delivery is a POST with a JSON body. X-SAU-Signature is sha256= plus the HMAC-SHA256 of the raw body using your secret, and X-SAU-Delivery is the event's id. Reply with a 2xx within 10 seconds. Each event is tried up to 6 times (immediately, then 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours after each failure) with the same id. After 20 failed deliveries in a row, the subscription is switched off. The catalogue has the headers, a signature check and the retry details.
Who can use them
Webhooks are managed with a Partner token. Account tokens get 403. A subscription id that isn't yours returns 404.
Endpoints
GET — See every event type we can send, with a description of each.
POST — Register a URL to receive events, choose immediate or batch delivery, and optionally filter which events you want.
POST — Send a test event to a subscription so you can check your endpoint receives it and your signature check passes.
GET — See recent delivery attempts to a subscription: what was sent, when, the response your endpoint gave, and any retries.
Updated 11 days ago