Webhook pranešimų apžvalga

Sursa kiekvienam svarbiam pakeitimui užregistruoja įvykį: kortelė paskelbiama, patikrinama ar archyvuojama, perskaitomas pranešimas, į klausimą neatsakoma. Įvykius galite gauti dviem būdais ir naudoti abu kartu:

	Webhook pranešimai	Įvykių juosta
Kaip	Sursa kiekvieną įvykį siunčia jūsų HTTPS adresu, kai tik jis įvyksta.	Skaitote `GET /v1/webhook-events`, kada norite.
Delsa	Sekundės.	Priklauso nuo to, kaip dažnai tikrinate.
Ko reikia	Viešo HTTPS gavėjo.	Tik API rakto su vaidmeniu `admin` ir apimtimi `webhooks:manage`.
Kam tinka	Reagavimui į pakeitimus: pranešti, sinchronizuoti, paleisti darbo eigą.	Paketiniams darbams, atsilikimui po prastovos pasivyti, suderinimui.

Abu būdai perduoda tuos pačius įvykius su tais pačiais ID. Kiekvienas įvykis juostoje saugomas 30 dienų, nepriklausomai nuo to, ar jį prenumeravo koks nors webhook galinis taškas.

Įvykis

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

Laukas	Reikšmė
`id`	Įvykio ID: `evt_` ir 32 šešioliktainiai simboliai. Tas pats per kiekvieną pristatymo bandymą ir juostoje.
`type`	Kas įvyko, forma `<object>.<past-tense verb>`: `card.updated`, `access_request.resolved`.
`created_at`	Kada įvyko pakeitimas, UTC.
`api_version`	API versija, kurios schemą atitinka `data`.
`object`	Objekto, apie kurį yra įvykis, tipas ir ID.
`data`	Išsami informacija. Jos forma priklauso nuo tipo ir aprašyta įvykių kataloge.
`data.previous_attributes`	`*.updated` įvykiuose: ankstesnės pasikeitusių laukų reikšmės.
`sequence`, `payload`, `test`	Tik webhook pristatymuose: vieta galinio taško eilėje, turinio režimas ir ar tai bandomasis įvykis.

data yra tik tai, ką bet kuris objekto skaitytojas galėtų matyti per API. Jame niekada nebūna prieigos sąrašų, kitų žmonių leidimų ar paslėptų laukų. Priežastys įvykiuose – trumpi neutralūs kodai, pavyzdžiui, no_hits, restricted arba index_failed.

Įvykių tipai

Įvykiai apima šias sritis:

Sritis	Pavyzdžiai
Kortelės	`card.created`, `card.updated`, `card.published`, `card.archived`, `card.deleted`, `card.indexed`, `card.index_failed`
Tikrinimas	`card.verified`, `card.unverified`, `verification.expired`, `verification.requested`
Struktūra	`collection.created`, `folder.updated`
Bendradarbiavimas	`comment.created`, `draft.publish_requested`, `announcement.sent`, `announcement.read`
Atsakymai	`question.unanswered`, `question.feedback_created`, `access_request.created`
Žmonės ir prieiga	`user.created`, `user.deactivated`, `group.member_added`, `api_key.expiring`
Šaltiniai ir importas	`source.sync_completed`, `import.sync_completed`, `import.document_failed`
Darbai	`job.completed`, `job.failed`, `export.ready`
Webhook pranešimai	`webhook.endpoint_disabled`, `webhook.ping`

Visas sąrašas su kiekvieno įvykio schema ir pavyzdžiu pateiktas API žinyno įvykių kataloge. GET /v1/webhooks/catalog grąžina jūsų diegime prieinamus tipus.

Laikui bėgant pridedama naujų įvykių tipų, o esami įvykiai gauna naujų laukų. Įvykių tipai niekada nepervadinami ir nepašalinami. Jūsų gavėjas privalo praleisti nežinomus tipus ir laukus.

Kas ką gauna

Galinis taškas gauna įvykį tik tada, kai įvykio objektas jam matomas – taip pat kaip API raktui: pagal jo vaidmenį, duomenų profilį ir rinkinius. Rinkiniu support apribotas galinis taškas niekada negauna įvykių apie korteles rinkinyje finance. Įvykiai apie žmones, raktus, šaltinius, importą, darbus, eksportą, atsiskaitymus, programas ir pačius webhook galinius taškus siunčiami tik galiniams taškams su vaidmeniu admin.

Šiose ribose kiekvienas galinis taškas pasirenka savo įvykius:

pagal tipą, su kaukėmis: card.* – visi kortelių įvykiai, * – visi įvykiai;
pagal rinkinį ir žymą – kortelių įvykiams.

Galinio taško turinio režimas yra full (įvykis su data, numatytasis) arba thin (įvykis be data: jūsų gavėjas objektą nuskaito per API savo raktu ir visada mato dabartinę jo būseną).

Pristatymas trumpai

HTTPS POST su įvykiu JSON formatu, pasirašytu galinio taško paslaptimi dviem formatais: Standard Webhooks (webhook-signature) ir ankstesniu X-KB-Signature.
Bet koks 2xx atsakas per 10 sekundžių laikomas sėkme.
Nepavykęs pristatymas kartojamas beveik tris dienas vis ilgesnėmis pauzėmis. Atsižvelgiama į Retry-After atsake 429 arba 503; 410 išjungia galinį tašką; 10 nesėkmių iš eilės jį pristabdo, kol jis bus vėl įjungtas.
Pristatymai vienam galiniam taškui siunčiami griežtai iš eilės. Lėtas galinis taškas nevėlina kitų galinių taškų.
Tas pats įvykis gali ateiti daugiau nei kartą: dublikatus atmeskite pagal webhook-id.

Webhook pranešimų gavimas žingsnis po žingsnio parodo visą gavėją su parašo tikrinimu Node.js, Python ir Go kalbomis.

Galinių taškų valdymas

Užduotis	Operacija
Sukurti galinį tašką ir gauti jo paslaptį	`POST /v1/webhooks`
Pakeisti adresą, įvykius ar būseną	`PATCH /v1/webhooks/{webhook_id}`
Išsiųsti bandomąjį įvykį	`POST /v1/webhooks/{webhook_id}/test`
Pakeisti paslaptį (rotacija)	`POST /v1/webhooks/{webhook_id}/rotate-secret`
Vėl įjungti pristabdytą galinį tašką	`POST /v1/webhooks/{webhook_id}/resume`
Peržiūrėti pristatymus ir atsakus	`GET /v1/webhooks/{webhook_id}/deliveries`
Pristatyti dar kartą	`POST /v1/webhooks/{webhook_id}/deliveries/{delivery_id}/redeliver`

Galiniams taškams valdyti reikia rakto su vaidmeniu admin ir apimtimi webhooks:manage arba administratoriaus administravimo sąsajoje. Organizacija gali turėti iki 20 galinių taškų. Webhook pranešimai priklauso nuo organizacijos plano; jei planas jų neapima, šios operacijos grąžina 403 su kodu webhooks.feature_disabled.