Webhook paziņojumu pārskats

Sursa reģistrē notikumu katrai svarīgai izmaiņai: kartīte ir publicēta, pārbaudīta vai arhivēta, paziņojums ir izlasīts, jautājums paliek neatbildēts. Notikumus var saņemt divos veidos, un abus var izmantot kopā:

	Webhook paziņojumi	Notikumu plūsma
Kā	Sursa sūta katru notikumu uz jūsu HTTPS adresi, tiklīdz tas notiek.	Jūs lasāt `GET /v1/webhook-events`, kad vēlaties.
Aizkave	Sekundes.	Tik bieži, cik bieži aptaujājat.
Vajadzīgs	Publisks HTTPS saņēmējs.	Tikai API atslēga ar lomu `admin` un tvērumu `webhooks:manage`.
Piemērots	Reaģēšanai uz izmaiņām: paziņot, sinhronizēt, sākt darbplūsmu.	Periodiskiem darbiem, datu atjaunošanai pēc dīkstāves, saskaņošanai.

Abos ir tie paši notikumi ar tiem pašiem ID. Katrs notikums plūsmā tiek glabāts 30 dienas neatkarīgi no tā, vai kāds webhook galapunkts to ir abonējis.

Notikums

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

Lauks	Nozīme
`id`	Notikuma ID: `evt_` un 32 heksadecimālas rakstzīmes. Tas pats katrā piegādes mēģinājumā un plūsmā.
`type`	Kas notika, formā `<object>.<past-tense verb>`: `card.updated`, `access_request.resolved`.
`created_at`	Kad izmaiņa notika, UTC laikā.
`api_version`	API versija, kuras shēmai atbilst `data`.
`object`	Tā objekta tips un ID, uz kuru notikums attiecas.
`data`	Sīkāka informācija. Tās forma ir atkarīga no tipa un aprakstīta notikumu katalogā.
`data.previous_attributes`	`*.updated` notikumos: mainīto lauku iepriekšējās vērtības.
`sequence`, `payload`, `test`	Tikai webhook piegādēs: pozīcija galapunkta secībā, satura režīms un pazīme, vai tas ir testa notikums.

data satur tikai to, ko jebkurš objekta lasītājs varētu redzēt caur API. Tajā nekad nav piekļuves sarakstu, citu cilvēku atļauju vai slēptu lauku. Iemesli notikumos ir īsi neitrāli kodi, piemēram, no_hits, restricted vai index_failed.

Notikumu tipi

Notikumi aptver šīs jomas:

Joma	Piemēri
Kartītes	`card.created`, `card.updated`, `card.published`, `card.archived`, `card.deleted`, `card.indexed`, `card.index_failed`
Pārbaude	`card.verified`, `card.unverified`, `verification.expired`, `verification.requested`
Struktūra	`collection.created`, `folder.updated`
Sadarbība	`comment.created`, `draft.publish_requested`, `announcement.sent`, `announcement.read`
Atbildes	`question.unanswered`, `question.feedback_created`, `access_request.created`
Cilvēki un piekļuve	`user.created`, `user.deactivated`, `group.member_added`, `api_key.expiring`
Avoti un imports	`source.sync_completed`, `import.sync_completed`, `import.document_failed`
Darbi	`job.completed`, `job.failed`, `export.ready`
Webhook paziņojumi	`webhook.endpoint_disabled`, `webhook.ping`

Pilns saraksts ar katra notikuma shēmu un piemēru ir API rokasgrāmatas notikumu katalogā. GET /v1/webhooks/catalog atgriež jūsu instalācijā pieejamos tipus.

Laika gaitā tiek pievienoti jauni notikumu tipi, un esošie notikumi iegūst jaunus laukus. Notikumu tipi nekad netiek pārdēvēti vai noņemti. Jūsu saņēmējam jāizlaiž tipi un lauki, kurus tas nepazīst.

Kas ko saņem

Galapunkts saņem notikumu tikai tad, ja notikuma objekts galapunktam ir redzams tāpat kā API atslēgai: pēc tā lomas, datu profila un kolekcijām. Galapunkts, kas ierobežots ar kolekciju support, nekad nesaņem notikumus par kartītēm kolekcijā finance. Notikumi par cilvēkiem, atslēgām, avotiem, importiem, darbiem, eksportiem, norēķiniem, lietotnēm un pašiem webhook galapunktiem tiek sūtīti tikai galapunktiem ar lomu admin.

Šo robežu ietvaros katrs galapunkts izvēlas savus notikumus:

pēc tipa, ar maskām: card.* – visiem kartīšu notikumiem, * – visiem notikumiem;
pēc kolekcijas un birkas – kartīšu notikumiem.

Galapunkta satura režīms ir full (notikums ar data, noklusējums) vai thin (notikums bez data: jūsu saņēmējs nolasa objektu caur API ar savu atslēgu un vienmēr redz tā pašreizējo stāvokli).

Īsumā par piegādi

HTTPS POST ar notikumu JSON formātā, parakstīts ar galapunkta noslēpumu divos formātos: Standard Webhooks (webhook-signature) un agrākajā X-KB-Signature.
Jebkura 2xx atbilde 10 sekunžu laikā ir veiksmīga piegāde.
Neizdevusies piegāde tiek atkārtota gandrīz trīs dienas ar pieaugošām pauzēm. Retry-After atbildē 429 vai 503 tiek ievērots; 410 atspējo galapunktu; 10 neveiksmes pēc kārtas to aptur, līdz tas tiek atsākts.
Piegādes vienam galapunktam tiek sūtītas stingri secīgi. Lēns galapunkts neaizkavē citus galapunktus.
Viens un tas pats notikums var pienākt vairāk nekā vienu reizi: dublikātus atmetiet pēc webhook-id.

Ceļvedis Webhook paziņojumu saņemšana soli pa solim parāda pilnu saņēmēju ar parakstu pārbaudi Node.js, Python un Go.

Galapunktu pārvaldība

Uzdevums	Operācija
Izveidot galapunktu un saņemt tā noslēpumu	`POST /v1/webhooks`
Mainīt adresi, notikumus vai stāvokli	`PATCH /v1/webhooks/{webhook_id}`
Nosūtīt testa notikumu	`POST /v1/webhooks/{webhook_id}/test`
Nomainīt noslēpumu pret jaunu vērtību	`POST /v1/webhooks/{webhook_id}/rotate-secret`
Atsākt apturētu galapunktu	`POST /v1/webhooks/{webhook_id}/resume`
Skatīt piegādes un atbildes	`GET /v1/webhooks/{webhook_id}/deliveries`
Nosūtīt piegādi vēlreiz	`POST /v1/webhooks/{webhook_id}/deliveries/{delivery_id}/redeliver`

Galapunktu pārvaldībai vajadzīga atslēga ar lomu admin un tvērumu webhooks:manage vai administrators administrēšanas saskarnē. Organizācijai var būt līdz 20 galapunktiem. Webhook paziņojumi ir daļa no organizācijas plāna; bez tiem šīs operācijas atbild ar 403 un kodu webhooks.feature_disabled.