Pregled webhookova

Sursa bilježi događaj za svaku važnu promjenu: kartica je objavljena, provjerena ili arhivirana, obavijest je pročitana, pitanje je ostalo bez odgovora. Događaje možete primati na dva načina i koristiti oba zajedno:

	Webhookovi	Feed događaja
Kako	Sursa šalje svaki događaj na vašu HTTPS adresu čim se dogodi.	Čitate `GET /v1/webhook-events` kad želite.
Kašnjenje	Sekunde.	Onoliko često koliko provjeravate.
Potrebno	Javni HTTPS primatelj.	Samo API ključ s ulogom `admin` i opsegom `webhooks:manage`.
Prikladno za	Reagiranje na promjene: obavijesti, sinkronizacija, pokretanje tijeka rada.	Skupne poslove, nadoknadu nakon zastoja, usklađivanje.

Oba nose iste događaje s istim ID-ovima. Svaki se događaj čuva u feedu 30 dana, bez obzira na to je li neki webhook bio pretplaćen na njega.

Događaj

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

Polje	Značenje
`id`	ID događaja, `evt_` i 32 heksadekadska znaka. Isti je u svakom pokušaju isporuke i u feedu.
`type`	Što se dogodilo, u obliku `<object>.<past-tense verb>`: `card.updated`, `access_request.resolved`.
`created_at`	Kad se promjena dogodila, u UTC-u.
`api_version`	Verzija API-ja čiju shemu slijedi `data`.
`object`	Vrsta i ID objekta na koji se događaj odnosi.
`data`	Pojedinosti. Njegov oblik ovisi o vrsti i opisan je u katalogu događaja.
`data.previous_attributes`	U događajima `*.updated`: ranije vrijednosti polja koja su se promijenila.
`sequence`, `payload`, `test`	Samo u isporukama webhookova: mjesto u redoslijedu webhooka, način tijela isporuke i je li riječ o probnom događaju.

data sadrži samo ono što bi svaki čitatelj objekta mogao vidjeti putem API-ja. Nikada ne sadrži popise pristupa, dopuštenja drugih osoba ni skrivena polja. Razlozi u događajima kratki su neutralni kodovi kao što su no_hits, restricted ili index_failed.

Vrste događaja

Događaji obuhvaćaju ova područja:

Područje	Primjeri
Kartice	`card.created`, `card.updated`, `card.published`, `card.archived`, `card.deleted`, `card.indexed`, `card.index_failed`
Provjera	`card.verified`, `card.unverified`, `verification.expired`, `verification.requested`
Struktura	`collection.created`, `folder.updated`
Suradnja	`comment.created`, `draft.publish_requested`, `announcement.sent`, `announcement.read`
Odgovori	`question.unanswered`, `question.feedback_created`, `access_request.created`
Osobe i pristup	`user.created`, `user.deactivated`, `group.member_added`, `api_key.expiring`
Izvori i uvoz	`source.sync_completed`, `import.sync_completed`, `import.document_failed`
Poslovi	`job.completed`, `job.failed`, `export.ready`
Webhookovi	`webhook.endpoint_disabled`, `webhook.ping`

Potpuni popis sa shemom i primjerom svakog događaja nalazi se u katalogu događaja u referenci API-ja. GET /v1/webhooks/catalog vraća vrste dostupne u vašoj instalaciji.

S vremenom se dodaju nove vrste događaja, a postojeći događaji dobivaju nova polja. Vrste događaja nikada se ne preimenuju i ne uklanjaju. Vaš primatelj mora preskakati vrste i polja koja ne poznaje.

Tko što prima

Webhook prima događaj samo ako mu je objekt događaja vidljiv, na isti način kao API ključu: prema njegovoj ulozi, podatkovnom profilu i zbirkama. Webhook ograničen na zbirku support nikada ne prima događaje o karticama u zbirci finance. Događaji o osobama, ključevima, izvorima, uvozima, poslovima, izvozima, naplati, aplikacijama i samim webhookovima idu samo webhookovima s ulogom admin.

Unutar toga svaki webhook bira svoje događaje:

prema vrsti, pomoću maski: card.* za svaki događaj kartice, * za svaki događaj;
prema zbirci i oznaci, za događaje kartica.

Način tijela isporuke webhooka je full (događaj s data, zadano) ili thin (događaj bez data: vaš primatelj čita objekt putem API-ja vlastitim ključem i uvijek vidi njegovo trenutačno stanje).

Ukratko o isporuci

HTTPS POST s događajem kao JSON-om, potpisan tajnom webhooka u dva formata: Standard Webhooks (webhook-signature) i ranijem X-KB-Signature.
Svaki odgovor 2xx unutar 10 sekundi smatra se uspjehom.
Neuspjela isporuka ponavlja se gotovo tri dana sa sve duljim stankama. Retry-After u odgovoru 429 ili 503 poštuje se; 410 isključuje webhook; 10 neuspjeha zaredom pauzira ga dok se njegov rad ne nastavi.
Isporuke jednom webhooku šalju se strogo redom. Spori webhook ne odgađa druge webhookove.
Isti događaj može stići više puta: duplikate odbacujte prema webhook-id.

Primanje webhookova korak po korak prikazuje potpunog primatelja, s provjerom potpisa u Node.js-u, Pythonu i Go-u.

Upravljanje webhookovima

Zadatak	Operacija
Stvaranje webhooka i dohvaćanje njegove tajne	`POST /v1/webhooks`
Promjena adrese, događaja ili stanja	`PATCH /v1/webhooks/{webhook_id}`
Slanje probnog događaja	`POST /v1/webhooks/{webhook_id}/test`
Rotacija tajne	`POST /v1/webhooks/{webhook_id}/rotate-secret`
Nastavak rada pauziranog webhooka	`POST /v1/webhooks/{webhook_id}/resume`
Pregled isporuka i odgovora	`GET /v1/webhooks/{webhook_id}/deliveries`
Ponovno slanje isporuke	`POST /v1/webhooks/{webhook_id}/deliveries/{delivery_id}/redeliver`

Za upravljanje webhookovima potreban je ključ s ulogom admin i opsegom webhooks:manage ili administrator u administratorskom sučelju. Organizacija može imati do 20 webhookova. Webhookovi su dio plana organizacije; bez njih ove operacije odgovaraju s 403 i kodom webhooks.feature_disabled.