Subscriptions

Endpoint reference for path-scoped event subscriptions. For the concept, see Events and Webhooks.

Subscriptions differ from webhooks: they scope to specific paths, and they support polling as a delivery mechanism (useful when your service can't receive inbound HTTP).

Base path: /v1/subscriptions/

GET /v1/subscriptions#

List subscriptions.

Scope: subscriptions:read.

POST /v1/subscriptions#

Create.

Body:

Field	Required	Description
`name`	Yes
`paths`	Yes	Array of globs
`events`	Yes	Event types
`delivery.type`	Yes	`webhook` or `polling`
`delivery.url`	For webhook
`delivery.secret`	For webhook	Signing secret
`delivery.buffer_size`	For polling	Max queued events (default 1000)
`filters`	No	Extra filters

Response 201 Created: id, name, status, identity_id (the caller — subscriptions are owned).

Scope: subscriptions:write.

GET /v1/subscriptions/{id}#

PATCH /v1/subscriptions/{id}#

Update paths, events, delivery.

DELETE /v1/subscriptions/{id}#

GET /v1/subscriptions/{id}/poll#

Long-poll for events. Blocks until an event arrives or timeout elapses.

Query:

Name	Type	Description
`timeout`	seconds	Up to 60, default 30
`since_event_id`	string	Deliver events after this ID
`max_events`	integer	Default 100

Response:

json
{
  "events": [
    {
      "event_id": "evt_01HK...",
      "event_type": "secret.rotated",
      "timestamp": "...",
      "path": "integrations/salesforce/oauth",
      "data": {"old_version": 3, "new_version": 4}
    }
  ],
  "has_more": false
}

On timeout with no events, returns {"events": [], "has_more": false}.

Scope: subscription owner only.

POST /v1/subscriptions/{id}/ack#

Acknowledge processed events (for polling delivery). Without ack, events re-deliver on reconnect.

Body: {"event_ids": ["evt_abc", "evt_def"]}.