Преглед вебхукова

Sursa бележи догађај за сваку важну измену: картица је објављена, проверена или архивирана, обавештење је прочитано, питање је остало без одговора. Догађаје можете да примате на два начина и да оба користите истовремено:

	Вебхукови	Фид догађаја
Како	Sursa шаље сваки догађај на вашу HTTPS адресу чим се деси.	Читате `GET /v1/webhook-events` када желите.
Кашњење	Неколико секунди.	Зависи од тога колико често проверавате.
Потребно	Јавни HTTPS прималац.	Само API кључ са улогом `admin` и опсегом `webhooks:manage`.
Погодно за	Реаговање на измене: обавештавање, синхронизацију, покретање радног тока.	Пакетне послове, надокнађивање после прекида рада, усклађивање.

Оба начина доносе исте догађаје са истим идентификаторима. Сваки догађај се чува у фиду 30 дана, без обзира на то да ли је иједан вебхук био претплаћен на њега.

Догађај

{
  "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
}

Поље	Значење
`id`	ID догађаја, `evt_` и 32 хексадецимална знака. Исти је у сваком покушају испоруке и у фиду.
`type`	Шта се десило, у облику `<object>.<past-tense verb>`: `card.updated`, `access_request.resolved`.
`created_at`	Када се измена десила, у UTC.
`api_version`	Верзија API интерфејса чију шему прати `data`.
`object`	Тип и ID објекта на који се догађај односи.
`data`	Детаљи. Облик зависи од типа и описан је у каталогу догађаја.
`data.previous_attributes`	У догађајима `*.updated`: раније вредности поља која су се променила.
`sequence`, `payload`, `test`	Само у испорукама вебхукова: позиција у редоследу испорука вебхука, режим тела испоруке и да ли је ово пробни догађај.

data садржи само оно што би сваки читалац објекта могао да види преко API интерфејса. Никада не садржи листе приступа, дозволе других људи ни скривена поља. Разлози у догађајима су кратки неутрални кодови, као што су no_hits, restricted или index_failed.

Типови догађаја

Догађаји обухватају ове области:

Област	Примери
Картице	`card.created`, `card.updated`, `card.published`, `card.archived`, `card.deleted`, `card.indexed`, `card.index_failed`
Провера	`card.verified`, `card.unverified`, `verification.expired`, `verification.requested`
Структура	`collection.created`, `folder.updated`
Сарадња	`comment.created`, `draft.publish_requested`, `announcement.sent`, `announcement.read`
Одговори	`question.unanswered`, `question.feedback_created`, `access_request.created`
Људи и приступ	`user.created`, `user.deactivated`, `group.member_added`, `api_key.expiring`
Извори и увоз	`source.sync_completed`, `import.sync_completed`, `import.document_failed`
Послови	`job.completed`, `job.failed`, `export.ready`
Вебхукови	`webhook.endpoint_disabled`, `webhook.ping`

Комплетна листа, са шемом и примером сваког догађаја, налази се у каталогу догађаја API референце. GET /v1/webhooks/catalog враћа типове доступне у вашој инсталацији.

Нови типови догађаја додају се с времена на време, а постојећи догађаји добијају нова поља. Типови догађаја никада не добијају ново име и не уклањају се. Ваш прималац мора да прескаче типове и поља које не познаје.

Ко шта прима

Вебхук прима догађај само ако му је објекат догађаја видљив, на исти начин као API кључу: према његовој улози, профилу приступа и колекцијама. Вебхук ограничен на колекцију support никада не прима догађаје о картицама у finance. Догађаји о људима, кључевима, изворима, увозима, пословима, извозима, наплати, апликацијама и самим вебхуковима иду само вебхуковима са улогом admin.

У тим оквирима сваки вебхук бира своје догађаје:

по типу, помоћу маски: card.* за сваки догађај картице, * за сваки догађај;
по колекцији и по ознаци, за догађаје картица.

Режим тела испоруке вебхука је full (догађај са data, подразумевано) или thin (догађај без data: ваш прималац чита објекат преко API интерфејса сопственим кључем и увек види његово тренутно стање).

Укратко о испоруци

HTTPS POST са догађајем као JSON, потписан тајном вебхука у два формата: Standard Webhooks (webhook-signature) и ранији X-KB-Signature.
Сваки одговор 2xx у року од 10 секунди сматра се успехом.
Неуспела испорука понавља се скоро три дана, са све дужим паузама. Retry-After у одговору 429 или 503 се поштује; 410 искључује вебхук; 10 неуспеха заредом паузира га док се његов рад не настави.
Испоруке једном вебхуку шаљу се строго по редоследу. Спор вебхук не задржава друге вебхукове.
Исти догађај може да стигне више пута: дупликате одбаците по webhook-id.

Пријем вебхукова води кроз комплетног примаоца, са провером потписа у Node.js, Python и Go.

Управљање вебхуковима

Задатак	Операција
Креирање вебхука и добијање његове тајне	`POST /v1/webhooks`
Измена адресе, догађаја или стања	`PATCH /v1/webhooks/{webhook_id}`
Слање пробног догађаја	`POST /v1/webhooks/{webhook_id}/test`
Ротација тајне	`POST /v1/webhooks/{webhook_id}/rotate-secret`
Наставак рада паузираног вебхука	`POST /v1/webhooks/{webhook_id}/resume`
Преглед испорука и одговора	`GET /v1/webhooks/{webhook_id}/deliveries`
Поновно слање испоруке	`POST /v1/webhooks/{webhook_id}/deliveries/{delivery_id}/redeliver`

За управљање вебхуковима потребан је кључ са улогом admin и опсегом webhooks:manage или администратор у администраторском интерфејсу. Организација може да има до 20 вебхукова. Вебхукови су део плана организације; без њих ове операције одговарају са 403 и кодом webhooks.feature_disabled.