Event pull subscriptions

Event subscriptions tell you that something changed on a website, so you know when to read it again through the REST API. Events are payload-free receipts: they contain no message text, personal data or resource IDs.

You need website_read and event_read. The credential must be unrestricted, and it can’t be a human-consent OAuth token.

Set up a subscription

Create the subscription.

curl -s -X POST "$GATEWAY/api/v1/subscriptions" \
  -H "Authorization: Bearer $INSIDE_GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sub-create-0001" \
  -d '{"website_ids":["web_4927_123"],"event_types":["conversation.*"],"payload_mode":"thin","delivery":{"mode":"pull"},"start":"beginning"}'

The 201 response contains the subscription and an initial cursor.

Pull events.

curl -s "$GATEWAY/api/v1/events?subscription_id=sub_...&after=<cursor>&limit=25" \
  -H "Authorization: Bearer $INSIDE_GATEWAY_TOKEN"

Store next_cursor and keep going while has_more is true, even if events is empty.
Read current data for the websites that changed, using the REST API.

Event types

Event families are conversation, visitor, operator, queue, website, privacy and capture. Each has five types:

Type	Meaning
`.changed`	Something in the family changed
`.removed`	Something in the family was removed
`.snapshot`	A full-state checkpoint
`.gap`	Events may have been missed; reconcile with REST reads
`.heartbeat`	The feed is alive with nothing new

Use an exact type such as conversation.changed, or a family wildcard such as conversation.*.

What an event contains

{
  "event_id": "evt_...",
  "event_type": "conversation.changed",
  "website_id": "web_4927_123",
  "cursor": 42,
  "occurred_at": 1760313600000,
  "recorded_at": 1760313600120
}

Times are Unix milliseconds. Deduplicate on event_id.

Manage subscriptions

Up to 50 websites per subscription, and up to 20 subscriptions per installation.
PATCH replaces the whole definition and DELETE removes it. Both need If-Match: "<revision>". After a replace, old cursors stop working; use the new cursor from the response.
Create, replace and delete accept an optional Idempotency-Key.

Recover from problems

Response	Meaning	What to do
`409 replay_expired`	Retained history has expired.	Reconcile with REST reads, then replace the subscription with `"start":"retained"`.
`503 event_family_paused`	Delivery is paused.	Keep your cursor and retry later.