Webhookien yleiskatsaus

Sursa kirjaa tapahtuman jokaisesta tärkeästä muutoksesta: kortti julkaistaan, vahvistetaan tai arkistoidaan, tiedote luetaan, kysymys jää vaille vastausta. Voit vastaanottaa tapahtumia kahdella tavalla ja käyttää molempia yhdessä:

	Webhookit	Tapahtumasyöte
Miten	Sursa lähettää jokaisen tapahtuman HTTPS-osoitteeseesi heti, kun se tapahtuu.	Luet syötettä `GET /v1/webhook-events` silloin, kun haluat.
Viive	Sekunteja.	Niin usein kuin kyselet.
Tarvitaan	Julkinen HTTPS-vastaanottaja.	Vain API-avain, jolla on rooli `admin` ja käyttöalue `webhooks:manage`.
Sopii	Muutoksiin reagoimiseen: ilmoita, synkronoi, käynnistä työnkulku.	Erätöihin, käyttökatkon jälkeiseen kiinnikuromiseen ja täsmäytykseen.

Molemmat välittävät samat tapahtumat samoilla tunnuksilla. Jokainen tapahtuma säilyy syötteessä 30 päivää riippumatta siitä, onko mikään webhook tilannut sen.

Tapahtuma

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

Kenttä	Merkitys
`id`	Tapahtuman tunnus: `evt_` ja 32 heksadesimaalimerkkiä. Sama jokaisessa toimitusyrityksessä ja syötteessä.
`type`	Mitä tapahtui, muodossa `<object>.<past-tense verb>`: `card.updated`, `access_request.resolved`.
`created_at`	Milloin muutos tapahtui, UTC-ajassa.
`api_version`	Se API:n versio, jonka skeemaa `data` noudattaa.
`object`	Sen objektin tyyppi ja tunnus, jota tapahtuma koskee.
`data`	Yksityiskohdat. Rakenne riippuu tyypistä, ja se on kuvattu tapahtumaluettelossa.
`data.previous_attributes`	`*.updated`-tapahtumissa: muuttuneiden kenttien aiemmat arvot.
`sequence`, `payload`, `test`	Vain webhook-toimituksissa: sijainti webhookin toimitusjärjestyksessä, hyötykuorman tila ja tieto siitä, onko kyseessä testitapahtuma.

data sisältää vain sen, minkä kuka tahansa objektin lukija voisi nähdä API:n kautta. Se ei koskaan sisällä käyttöoikeusluetteloita, muiden ihmisten käyttöoikeuksia eikä piilotettuja kenttiä. Tapahtumien syyt ovat lyhyitä neutraaleja koodeja, kuten no_hits, restricted tai index_failed.

Tapahtumatyypit

Tapahtumat kattavat nämä alueet:

Alue	Esimerkkejä
Kortit	`card.created`, `card.updated`, `card.published`, `card.archived`, `card.deleted`, `card.indexed`, `card.index_failed`
Vahvistus	`card.verified`, `card.unverified`, `verification.expired`, `verification.requested`
Rakenne	`collection.created`, `folder.updated`
Yhteistyö	`comment.created`, `draft.publish_requested`, `announcement.sent`, `announcement.read`
Vastaukset	`question.unanswered`, `question.feedback_created`, `access_request.created`
Ihmiset ja käyttöoikeudet	`user.created`, `user.deactivated`, `group.member_added`, `api_key.expiring`
Lähteet ja tuonti	`source.sync_completed`, `import.sync_completed`, `import.document_failed`
Työt	`job.completed`, `job.failed`, `export.ready`
Webhookit	`webhook.endpoint_disabled`, `webhook.ping`

Täydellinen luettelo kunkin tapahtuman skeemoineen ja esimerkkeineen on API-viitteen tapahtumaluettelossa. GET /v1/webhooks/catalog palauttaa asennuksessasi käytettävissä olevat tyypit.

Uusia tapahtumatyyppejä lisätään ajan mittaan, ja olemassa olevat tapahtumat saavat uusia kenttiä. Tapahtumatyyppejä ei koskaan nimetä uudelleen eikä poisteta. Vastaanottajasi täytyy ohittaa tyypit ja kentät, joita se ei tunne.

Kuka vastaanottaa mitä

Webhook vastaanottaa tapahtuman vain, jos tapahtuman objekti näkyy webhookille samalla tavalla kuin API-avaimelle: sen roolin, dataprofiilin ja kokoelmien mukaan. Webhook, joka on rajattu support-kokoelmaan, ei koskaan vastaanota tapahtumia finance-kokoelman korteista. Ihmisiä, avaimia, lähteitä, tuonteja, töitä, vientejä, laskutusta, sovelluksia ja itse webhookeja koskevat tapahtumat menevät vain webhookeille, joilla on rooli admin.

Näissä rajoissa jokainen webhook valitsee tapahtumansa:

tyypin mukaan maskeilla: card.* kaikille korttitapahtumille, * kaikille tapahtumille;
korttitapahtumissa kokoelman ja tunnisteen mukaan.

Webhookin hyötykuorman tila on full (tapahtuma data-kenttineen, oletus) tai thin (tapahtuma ilman data-kenttää: vastaanottajasi lukee objektin API:n kautta omalla avaimellaan ja näkee aina sen nykyisen tilan).

Toimitus lyhyesti

HTTPS:n kautta lähetettävä POST-pyyntö, jossa tapahtuma on JSON-muodossa ja joka on allekirjoitettu webhookin salaisuudella kahdessa muodossa: Standard Webhooks (webhook-signature) ja aiempi X-KB-Signature.
Mikä tahansa 2xx-vastaus 10 sekunnin kuluessa on onnistuminen.
Epäonnistunutta toimitusta yritetään uudelleen lähes kolmen päivän ajan yhä pidemmin tauoin. 429- tai 503-vastauksen Retry-After otetaan huomioon; 410 poistaa webhookin käytöstä; 10 peräkkäistä epäonnistumista keskeyttää sen, kunnes sen toimintaa jatketaan.
Saman webhookin toimitukset lähetetään tiukasti järjestyksessä. Hidas webhook ei viivästytä muita webhookeja.
Sama tapahtuma voi saapua useammin kuin kerran: hylkää kaksoiskappaleet webhook-id-otsakkeen mukaan.

Webhookien vastaanottaminen käy läpi kokonaisen vastaanottajan allekirjoitusten tarkistuksineen Node.js:llä, Pythonilla ja Go:lla.

Webhookien hallinta

Tehtävä	Päätepiste
Luo webhook ja hae sen salaisuus	`POST /v1/webhooks`
Muuta osoitetta, tapahtumia tai tilaa	`PATCH /v1/webhooks/{webhook_id}`
Lähetä testitapahtuma	`POST /v1/webhooks/{webhook_id}/test`
Uusi salaisuus	`POST /v1/webhooks/{webhook_id}/rotate-secret`
Jatka keskeytetyn webhookin toimintaa	`POST /v1/webhooks/{webhook_id}/resume`
Katso toimitukset ja vastaukset	`GET /v1/webhooks/{webhook_id}/deliveries`
Lähetä toimitus uudelleen	`POST /v1/webhooks/{webhook_id}/deliveries/{delivery_id}/redeliver`

Webhookien hallintaan tarvitaan avain, jolla on rooli admin ja käyttöalue webhooks:manage, tai ylläpitäjä ylläpitonäkymässä. Organisaatiolla voi olla enintään 20 webhookia. Webhookit kuuluvat organisaation pakettiin; ilman niitä nämä päätepisteet palauttavat 403-vastauksen ja koodin webhooks.feature_disabled.