Общ преглед на уебхуковете

Sursa записва събитие за всяка важна промяна: карта е публикувана, проверена или архивирана, съобщение е прочетено, въпрос е останал без отговор. Може да получавате събитията по два начина и да използвате двата заедно:

И двата начина носят едни и същи събития със същите ID. Всяко събитие се пази в лентата 30 дни, независимо дали някой уебхук е бил абониран за него.

Събитието

{
  "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 съдържа само онова, което всеки читател на обекта би могъл да види през API. То никога не съдържа списъци за достъп, правата на други хора или скрити полета. Причините в събитията са кратки неутрални кодове като no_hits, restricted или index_failed.

Типове събития

Събитията обхващат следните области:

Пълният списък със схемата и пример за всяко събитие е в каталога на събитията в справочника на API. GET /v1/webhooks/catalog връща типовете, налични във вашата инсталация.

С времето се добавят нови типове събития, а съществуващите събития получават нови полета. Типовете събития никога не се преименуват и не се премахват. Получателят ви трябва да пропуска типовете и полетата, които не познава.

Кой какво получава

Уебхукът получава събитие само ако обектът на събитието е видим за него – по същия начин, както за API ключ: според ролята, профила за достъп и колекциите му. Уебхук, ограничен до колекцията support, никога не получава събития за карти във finance. Събитията за хора, ключове, източници, импорти, задания, експорти, плащания, приложения и за самите уебхукове отиват само към уебхуковете с ролята admin.

В тези граници всеки уебхук избира своите събития:

• по тип, с маски: card.* за всяко събитие на карта, * за всяко събитие;
• по колекция и по етикет – за събитията на карти.

Режимът на тялото на уебхука е full (събитието с data, по подразбиране) или thin (събитието без data: получателят ви чете обекта през API със собствен ключ и винаги вижда текущото му състояние).

Накратко за доставката

• HTTPS POST със събитието като JSON, подписан с тайната на уебхука в два формата: Standard Webhooks (webhook-signature) и по-ранния X-KB-Signature.
• Всеки отговор 2xx до 10 секунди е успех.
• При неуспех доставката се повтаря в продължение на почти три дни с нарастващи паузи. Retry-After в отговор 429 или 503 се спазва; 410 изключва уебхука; 10 поредни неуспеха го спират временно, докато не бъде възобновен.
• Доставките към един уебхук се изпращат строго по ред. Бавен уебхук не забавя другите уебхукове.
• Едно и също събитие може да пристигне повече от веднъж: отхвърляйте дубликатите по webhook-id.

Получаване на уебхукове показва стъпка по стъпка цялостен получател с проверка на подписа на Node.js, Python и Go.

Управление на уебхуковете

За управлението на уебхуковете е нужен ключ с ролята admin и обхвата webhooks:manage или администратор в интерфейса за администриране. Една организация може да има до 20 уебхука. Уебхуковете са част от плана на организацията; без тях тези операции отговарят с 403 и кода webhooks.feature_disabled.