Analytics webhooks

Events for the background analytics sync. Delivery, retries, idempotency, and signature verification work the same for every event and are covered in the webhooks overview.

Events

---

analytics.synced

Fired once per connected account each time its analytics sync cycle completes successfully. Subscribe with Create webhook settings or Update webhook settings.

A trigger, not a transport

The payload deliberately carries no metrics. It tells you that an account's analytics changed, not what changed.

sync.cursor is an opaque GET /v1/analytics/delta cursor positioned just before this cycle's rows. Pass it straight to the delta feed and one call returns every post whose analytics changed, across every account you can see. That replaces the common pattern of polling GET /v1/analytics once per connected account, where a fleet of 1,000 accounts costs 1,000 requests an hour.

The two are designed to be used together:

1. Bootstrap your baseline once from GET /v1/analytics.
2. Receive analytics.synced.
3. Call GET /v1/analytics/delta with the cursor you were given, then keep sending back each nextCursor.

If you would rather not run a webhook consumer at all, skip this event and poll the delta feed on a timer instead. The feed is the source of truth either way.

Do not read an empty page as "nothing changed"

The delta feed is backed by a materialized view, so a read issued the instant this event lands may legitimately return an empty data array while the rows are still landing.

Re-poll with the same cursor rather than advancing. Advancing on an empty page is the one way to lose changes permanently.

Volume

This fires per account, per successful sync cycle, and sync runs roughly hourly per account. The rate therefore scales with fleet size: an integration with around 1,500 connected accounts should expect on the order of 900 events an hour.

Two consequences worth planning for:

• Subscribe on a dedicated webhook endpoint. A subscription's consecutive-failure count is shared by every event on it, so putting a high-volume event alongside low-volume ones like post.published means an outage on the busy event can auto-disable the whole subscription and silence the others too.
• Your endpoint must return quickly. Acknowledge first, then do the delta read out of band.

Not fired when

• The sync cycle fails, or is skipped because the account was synced recently.
• The account is inactive or disconnected.
• The platform does not support analytics sync. See GET /v1/analytics for the supported set.