A webhookok áttekintése

A Sursa minden fontos változásról eseményt rögzít: egy kártyát közzétesznek, ellenőriznek vagy archiválnak, egy közleményt elolvasnak, egy kérdés megválaszolatlan marad. Az eseményeket kétféleképpen fogadhatod, és a kettőt együtt is használhatod:

Mindkettő ugyanazokat az eseményeket szállítja, ugyanazokkal az azonosítókkal. Minden esemény 30 napig megmarad a csatornában, függetlenül attól, hogy feliratkozott-e rá bármely webhook.

Az esemény

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

A data csak azt tartalmazza, amit az objektum bármely olvasója az API-n keresztül láthatna. Soha nem tartalmaz hozzáférési listákat, mások jogosultságait vagy rejtett mezőket. Az eseményekben szereplő indokok rövid semleges kódok, például no_hits, restricted vagy index_failed.

Eseménytípusok

Az események a következő területeket fedik le:

A teljes lista az egyes események sémájával és példájával az API-referencia eseménykatalógusában található. A GET /v1/webhooks/catalog a telepítéseden elérhető típusokat adja vissza.

Idővel új eseménytípusok jelennek meg, a meglévő események pedig új mezőket kapnak. Az eseménytípusokat soha nem nevezik át és nem távolítják el. A fogadódnak ki kell hagynia az általa nem ismert típusokat és mezőket.

Ki mit kap meg

Egy webhook csak akkor kap meg egy eseményt, ha az esemény objektuma látható a webhook számára, ugyanúgy, mint egy API-kulcs számára: a szerepköre, az adatprofilja és a gyűjteményei alapján. A support gyűjteményre korlátozott webhook soha nem kap eseményt a finance gyűjtemény kártyáiról. A személyekről, kulcsokról, forrásokról, importálásokról, feladatokról, exportálásokról, a számlázásról, az alkalmazásokról és magukról a webhookokról szóló események csak az admin szerepkörű webhookokhoz jutnak el.

Ezen belül minden webhook maga választja ki az eseményeit:

• típus szerint, mintákkal: card.* minden kártyaeseményhez, * minden eseményhez;
• gyűjtemény és címke szerint, a kártyaeseményeknél.

A webhook adattartalom-módja full (az esemény a data mezővel, ez az alapértelmezett) vagy thin (az esemény data nélkül: a fogadód a saját kulcsával olvassa ki az objektumot az API-n keresztül, és mindig az aktuális állapotát látja).

A kézbesítés röviden

• HTTPS POST kérés, JSON-ként az eseménnyel, a webhook titkos kulcsával kétféle formátumban aláírva: Standard Webhooks (webhook-signature) és a korábbi X-KB-Signature.
• Bármely 2xx válasz 10 másodpercen belül sikernek számít.
• A sikertelen kézbesítést a Sursa közel három napig próbálja újra, egyre hosszabb szünetekkel. A 429 vagy 503 válasz Retry-After fejlécét figyelembe veszi; a 410 válasz letiltja a webhookot; 10 egymást követő hiba szünetelteti, amíg újra nem indítják.
• Az egy webhooknak szóló kézbesítések szigorúan sorrendben mennek ki. Egy lassú webhook nem késlelteti a többit.
• Ugyanaz az esemény többször is megérkezhet: az ismétlődéseket a webhook-id alapján szűrd ki.

A Webhookok fogadása útmutató egy teljes fogadót mutat be, aláírás-ellenőrzéssel Node.js, Python és Go nyelven.

Webhookok kezelése

A webhookok kezeléséhez admin szerepkörű és webhooks:manage hatókörű kulcs kell, vagy egy adminisztrátor az adminisztrációs felületen. Egy szervezetnek legfeljebb 20 webhookja lehet. A webhookok a szervezet csomagjának részei; nélkülük ezek a végpontok 403 választ adnak a webhooks.feature_disabled kóddal.