Veebihaagide ülevaade

Sursa salvestab sündmuse iga olulise muudatuse kohta: kaart avaldatakse, kontrollitakse või arhiveeritakse, teadaanne loetakse, küsimus jääb vastuseta. Sündmusi saab vastu võtta kahel viisil ja mõlemat saab kasutada koos:

	Veebihaagid	Sündmuste lint
Kuidas	Sursa saadab iga sündmuse selle toimumisel teie HTTPS-aadressile.	Te loete lõpp-punkti `GET /v1/webhook-events` siis, kui soovite.
Viivitus	Sekundid.	Nii sageli, kui küsitlete.
Vajalik	Avalik HTTPS-vastuvõtja.	Ainult API-võti, millel on roll `admin` ja ulatus `webhooks:manage`.
Sobib	Muudatustele reageerimiseks: teavitamine, sünkroonimine, töövoo käivitamine.	Partiitöödeks, katkestuse järel järelejõudmiseks ja andmete vastavusse viimiseks.

Mõlemad kannavad samu sündmusi samade ID-dega. Iga sündmust säilitatakse lindis 30 päeva, olenemata sellest, kas mõni veebihaak oli selle tellinud.

Sündmus

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

Väli	Tähendus
`id`	Sündmuse ID: `evt_` ja 32 kuueteistkümnendsüsteemi märki. Sama igas edastuskatses ja lindis.
`type`	Mis juhtus, kujul `<object>.<past-tense verb>`: `card.updated`, `access_request.resolved`.
`created_at`	Millal muudatus toimus, UTC järgi.
`api_version`	API versioon, mille skeemi `data` järgib.
`object`	Selle objekti tüüp ja ID, mille kohta sündmus on.
`data`	Üksikasjad. Selle kuju sõltub tüübist ja seda kirjeldab sündmuste kataloog.
`data.previous_attributes`	Sündmustes `*.updated`: muutunud väljade varasemad väärtused.
`sequence`, `payload`, `test`	Ainult veebihaagi edastustes: koht veebihaagi edastuste järjekorras, sisu režiim ja see, kas tegu on testsündmusega.

data sisaldab ainult seda, mida objekti iga lugeja API kaudu näha võiks. See ei sisalda kunagi juurdepääsuloendeid, teiste inimeste õigusi ega peidetud välju. Sündmustes olevad põhjused on lühikesed neutraalsed koodid, näiteks no_hits, restricted või index_failed.

Sündmusetüübid

Sündmused hõlmavad järgmisi valdkondi:

Valdkond	Näited
Kaardid	`card.created`, `card.updated`, `card.published`, `card.archived`, `card.deleted`, `card.indexed`, `card.index_failed`
Kontroll	`card.verified`, `card.unverified`, `verification.expired`, `verification.requested`
Struktuur	`collection.created`, `folder.updated`
Koostöö	`comment.created`, `draft.publish_requested`, `announcement.sent`, `announcement.read`
Vastused	`question.unanswered`, `question.feedback_created`, `access_request.created`
Inimesed ja juurdepääs	`user.created`, `user.deactivated`, `group.member_added`, `api_key.expiring`
Allikad ja import	`source.sync_completed`, `import.sync_completed`, `import.document_failed`
Tööd	`job.completed`, `job.failed`, `export.ready`
Veebihaagid	`webhook.endpoint_disabled`, `webhook.ping`

Täielik loend iga sündmuse skeemi ja näitega on API teatmiku sündmuste kataloogis. GET /v1/webhooks/catalog tagastab teie paigalduses saadaolevad tüübid.

Aja jooksul lisandub uusi sündmusetüüpe ja olemasolevad sündmused saavad uusi välju. Sündmusetüüpe ei nimetata kunagi ümber ega eemaldata. Teie vastuvõtja peab tundmatud tüübid ja väljad vahele jätma.

Kes mida saab

Veebihaak saab sündmuse ainult siis, kui sündmuse objekt on veebihaagile nähtav samamoodi nagu API-võtmele: selle rolli, andmeprofiili ja kogude järgi. Koguga support piiratud veebihaak ei saa kunagi sündmusi kogus finance olevate kaartide kohta. Sündmused inimeste, võtmete, allikate, importide, tööde, eksportide, arvelduse, rakenduste ja veebihaakide endi kohta lähevad ainult veebihaakidele, millel on roll admin.

Nende piires valib iga veebihaak oma sündmused:

tüübi järgi, maskidega: card.* kõigi kaardisündmuste jaoks, * kõigi sündmuste jaoks;
kogu ja sildi järgi, kaardisündmuste puhul.

Veebihaagi sisu režiim on full (sündmus koos väljaga data, vaikimisi) või thin (sündmus ilma väljata data: teie vastuvõtja loeb objekti oma võtmega API kaudu ja näeb alati selle praegust olekut).

Edastus lühidalt

HTTPS-päring POST, mille kehas on sündmus JSON-ina ja mis on allkirjastatud veebihaagi saladusega kahes vormingus: Standard Webhooks (webhook-signature) ja varasem X-KB-Signature.
Iga 10 sekundi jooksul saabunud vastus 2xx tähendab edu.
Ebaõnnestunud edastust proovitakse peaaegu kolme päeva jooksul uuesti üha pikemate vahedega. Päist Retry-After vastuses 429 või 503 arvestatakse; 410 keelab veebihaagi; 10 järjestikust ebaõnnestumist peatavad veebihaagi, kuni selle töö jätkatakse.
Ühe veebihaagi edastused saadetakse rangelt järjekorras. Aeglane veebihaak ei viivita teisi veebihaake.
Sama sündmus võib saabuda rohkem kui üks kord: kõrvaldage duplikaadid väärtuse webhook-id järgi.

Juhend Veebihaagide vastuvõtmine tutvustab samm-sammult täielikku vastuvõtjat koos allkirja kontrollimisega Node.js-is, Pythonis ja Go-s.

Veebihaagide haldamine

Ülesanne	Lõpp-punkt
Veebihaagi loomine ja selle saladuse saamine	`POST /v1/webhooks`
Aadressi, sündmuste või oleku muutmine	`PATCH /v1/webhooks/{webhook_id}`
Testsündmuse saatmine	`POST /v1/webhooks/{webhook_id}/test`
Saladuse uuendamine	`POST /v1/webhooks/{webhook_id}/rotate-secret`
Peatatud veebihaagi töö jätkamine	`POST /v1/webhooks/{webhook_id}/resume`
Edastuste ja vastuste vaatamine	`GET /v1/webhooks/{webhook_id}/deliveries`
Edastuse uuesti saatmine	`POST /v1/webhooks/{webhook_id}/deliveries/{delivery_id}/redeliver`

Veebihaagide haldamiseks on vaja võtit, millel on roll admin ja ulatus webhooks:manage, või administraatorit haldusliideses. Organisatsioonil võib olla kuni 20 veebihaaki. Veebihaagid on osa organisatsiooni paketist; kui neid paketis ei ole, vastavad need lõpp-punktid 403 koodiga webhooks.feature_disabled.