Webhooks overview

Sursa records an event for every important change: a card is published, verified or archived, an announcement is read, a question goes unanswered. You can receive events in two ways, and use both together:

Both carry the same events with the same IDs. Every event is kept in the feed for 30 days, whether or not any webhook was subscribed to it.

The event

{
  "id": "evt_0123456789abcdef0123456789abcdef",
  "type": "card.updated",
  "created_at": "2026-10-24T10:00:03Z",
  "org_id": 1,
  "api_version": "1.60.0",
  "sequence": 1042,
  "object": {"type": "card", "id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"},
  "payload": "full",
  "data": {
    "card": {"id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60", "title": "Refund policy", "collection": "support", "version": 4},
    "actor_id": 7,
    "previous_attributes": {"title": "Refunds"}
  },
  "test": false
}

data holds only what any reader of the object could see through the API. It never contains access lists, the permissions of other people or hidden fields. Reasons in events are short neutral codes such as no_hits, restricted or index_failed.

Event types

Events cover these areas:

The complete list with the schema and an example of each event is in the event catalog of the API reference. GET /v1/webhooks/catalog returns the types available on your installation.

New event types are added over time, and existing events gain fields. Event types are never renamed or removed. Your receiver must skip types and fields it does not know.

Who receives what

An endpoint receives an event only if the object of the event is visible to the endpoint, in the same way as to an API key: by its role, its data profile and its collections. An endpoint limited to the support collection never receives events about cards in finance. Events about people, keys, sources, imports, jobs, exports, billing, applications and webhooks themselves go only to endpoints with the admin role.

Within that, each endpoint chooses its events:

• by type, with masks: card.* for every card event, * for every event;
• by collection and by tag, for card events.

The payload mode of an endpoint is full (the event with data, the default) or thin (the event without data: your receiver reads the object through the API with its own key, and always sees its current state).

Delivery in short

• An HTTPS POST with the event as JSON, signed with the endpoint's secret in two formats: Standard Webhooks (webhook-signature) and the earlier X-KB-Signature.
• Any 2xx answer within 10 seconds is a success.
• A failure is retried for almost three days with growing pauses. Retry-After in a 429 or 503 answer is respected; 410 disables the endpoint; 10 failures in a row pause it until it is resumed.
• Deliveries to one endpoint are sent strictly in order. A slow endpoint does not delay other endpoints.
• The same event can arrive more than once: drop duplicates by webhook-id.

Receive webhooks walks through a complete receiver, with signature checks in Node.js, Python and Go.

Manage endpoints

Managing endpoints needs a key with the admin role and the webhooks:manage scope, or an administrator in the admin interface. An organization can have up to 20 endpoints. Webhooks are part of the organization's plan; without them, these endpoints answer 403 with the code webhooks.feature_disabled.