Prezentare generală a webhookurilor

Sursa înregistrează un eveniment pentru fiecare modificare importantă: o fișă este publicată, verificată sau arhivată, un anunț este citit, o întrebare rămâne fără răspuns. Puteți primi evenimentele în două moduri și le puteți folosi pe amândouă împreună:

Ambele transportă aceleași evenimente, cu aceiași identificatori. Fiecare eveniment se păstrează în flux 30 de zile, indiferent dacă vreun webhook era abonat la el sau nu.

Evenimentul

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

data conține doar ce ar putea vedea prin API orice cititor al obiectului. Nu conține niciodată liste de acces, permisiunile altor persoane sau câmpuri ascunse. Motivele din evenimente sunt coduri neutre scurte, cum ar fi no_hits, restricted sau index_failed.

Tipuri de evenimente

Evenimentele acoperă aceste domenii:

Lista completă, cu schema și un exemplu pentru fiecare eveniment, se află în catalogul evenimentelor din referința API. GET /v1/webhooks/catalog returnează tipurile disponibile în instalarea dumneavoastră.

În timp se adaugă tipuri noi de evenimente, iar evenimentele existente primesc câmpuri noi. Tipurile de evenimente nu sunt niciodată redenumite sau eliminate. Receptorul trebuie să ignore tipurile și câmpurile pe care nu le cunoaște.

Cine ce primește

Un webhook primește un eveniment doar dacă obiectul evenimentului îi este vizibil, la fel ca unei chei API: după rolul, profilul de date și colecțiile lui. Un webhook limitat la colecția support nu primește niciodată evenimente despre fișele din finance. Evenimentele despre persoane, chei, surse, importuri, joburi, exporturi, facturare, aplicații și despre webhookurile înseși ajung doar la webhookurile cu rolul admin.

În aceste limite, fiecare webhook își alege evenimentele:

• după tip, cu măști: card.* pentru fiecare eveniment al fișelor, * pentru fiecare eveniment;
• după colecție și după etichetă, pentru evenimentele fișelor.

Modul conținutului unui webhook este full (evenimentul cu data, valoarea implicită) sau thin (evenimentul fără data: receptorul citește obiectul prin API cu propria cheie și vede întotdeauna starea lui curentă).

Livrarea pe scurt

• Un POST HTTPS cu evenimentul în format JSON, semnat cu secretul webhookului în două formate: Standard Webhooks (webhook-signature) și formatul anterior X-KB-Signature.
• Orice răspuns 2xx în cel mult 10 secunde este un succes.
• O livrare eșuată este reîncercată aproape trei zile, cu pauze din ce în ce mai lungi. Retry-After dintr-un răspuns 429 sau 503 este respectat; 410 dezactivează webhookul; 10 eșecuri consecutive îl pun în pauză până când este reluat.
• Livrările către un webhook sunt trimise strict în ordine. Un webhook lent nu întârzie alte webhookuri.
• Același eveniment poate sosi de mai multe ori: eliminați dublurile după webhook-id.

Primiți webhookuri prezintă pas cu pas un receptor complet, cu verificarea semnăturilor în Node.js, Python și Go.

Gestionarea webhookurilor

Gestionarea webhookurilor necesită o cheie cu rolul admin și domeniul webhooks:manage sau un administrator în interfața de administrare. O organizație poate avea cel mult 20 de webhookuri. Webhookurile fac parte din planul organizației; fără ele, aceste endpointuri răspund 403 cu codul webhooks.feature_disabled.