Przegląd webhooków

Sursa rejestruje zdarzenie przy każdej ważnej zmianie: karta zostaje opublikowana, zweryfikowana lub zarchiwizowana, ogłoszenie zostaje przeczytane, pytanie pozostaje bez odpowiedzi. Zdarzenia możesz odbierać na dwa sposoby i używać obu jednocześnie:

	Webhooki	Kanał zdarzeń
Jak	Sursa wysyła każde zdarzenie na Twój adres HTTPS w chwili, gdy ono nastąpi.	Odczytujesz `GET /v1/webhook-events`, kiedy chcesz.
Opóźnienie	Sekundy.	Zależy od tego, jak często odpytujesz.
Wymagania	Publiczny odbiorca HTTPS.	Tylko klucz API z rolą `admin` i zakresem `webhooks:manage`.
Zastosowanie	Reagowanie na zmiany: powiadomienie, synchronizacja, uruchomienie przepływu pracy.	Zadania wsadowe, nadrabianie zaległości po przestoju, uzgadnianie.

Oba sposoby przenoszą te same zdarzenia z tymi samymi identyfikatorami. Każde zdarzenie jest przechowywane w kanale przez 30 dni, niezależnie od tego, czy jakikolwiek webhook je subskrybował.

Zdarzenie

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

Pole	Znaczenie
`id`	ID zdarzenia: `evt_` i 32 znaki szesnastkowe. Takie samo w każdej próbie dostarczenia i w kanale.
`type`	Co się stało, w formie `<object>.<past-tense verb>`: `card.updated`, `access_request.resolved`.
`created_at`	Kiedy nastąpiła zmiana, w UTC.
`api_version`	Wersja API, której schematu przestrzega `data`.
`object`	Typ i ID obiektu, którego dotyczy zdarzenie.
`data`	Szczegóły. Ich struktura zależy od typu i jest opisana w katalogu zdarzeń.
`data.previous_attributes`	W zdarzeniach `*.updated`: wcześniejsze wartości pól, które się zmieniły.
`sequence`, `payload`, `test`	Tylko w dostarczeniach webhooków: pozycja w kolejności dostarczeń webhooka, tryb treści i informacja, czy to zdarzenie testowe.

data zawiera tylko to, co każdy czytelnik obiektu mógłby zobaczyć przez API. Nigdy nie zawiera list dostępu, uprawnień innych osób ani ukrytych pól. Przyczyny w zdarzeniach to krótkie kody neutralne, np. no_hits, restricted lub index_failed.

Typy zdarzeń

Zdarzenia obejmują następujące obszary:

Obszar	Przykłady
Karty	`card.created`, `card.updated`, `card.published`, `card.archived`, `card.deleted`, `card.indexed`, `card.index_failed`
Weryfikacja	`card.verified`, `card.unverified`, `verification.expired`, `verification.requested`
Struktura	`collection.created`, `folder.updated`
Współpraca	`comment.created`, `draft.publish_requested`, `announcement.sent`, `announcement.read`
Odpowiedzi	`question.unanswered`, `question.feedback_created`, `access_request.created`
Osoby i dostęp	`user.created`, `user.deactivated`, `group.member_added`, `api_key.expiring`
Źródła i import	`source.sync_completed`, `import.sync_completed`, `import.document_failed`
Zadania	`job.completed`, `job.failed`, `export.ready`
Webhooki	`webhook.endpoint_disabled`, `webhook.ping`

Pełna lista ze schematem i przykładem każdego zdarzenia znajduje się w katalogu zdarzeń w dokumentacji API. GET /v1/webhooks/catalog zwraca typy dostępne w Twojej instalacji.

Z czasem dodawane są nowe typy zdarzeń, a istniejące zdarzenia zyskują nowe pola. Typy zdarzeń nigdy nie zmieniają nazwy ani nie są usuwane. Twój odbiorca musi pomijać typy i pola, których nie zna.

Kto co otrzymuje

Webhook otrzymuje zdarzenie tylko wtedy, gdy obiekt zdarzenia jest dla niego widoczny, tak samo jak dla klucza API: według jego roli, profilu dostępu i kolekcji. Webhook ograniczony do kolekcji support nigdy nie otrzymuje zdarzeń o kartach w finance. Zdarzenia dotyczące osób, kluczy, źródeł, importów, zadań, eksportów, rozliczeń, aplikacji i samych webhooków trafiają tylko do webhooków z rolą admin.

W tych granicach każdy webhook wybiera swoje zdarzenia:

według typu, za pomocą masek: card.* dla każdego zdarzenia karty, * dla każdego zdarzenia;
według kolekcji i tagu – w przypadku zdarzeń kart.

Tryb treści webhooka to full (zdarzenie z data, domyślnie) lub thin (zdarzenie bez data: Twój odbiorca odczytuje obiekt przez API własnym kluczem i zawsze widzi jego bieżący stan).

Dostarczanie w skrócie

Żądanie HTTPS POST ze zdarzeniem w formacie JSON, podpisane sekretem webhooka w dwóch formatach: Standard Webhooks (webhook-signature) i wcześniejszym X-KB-Signature.
Każda odpowiedź 2xx w ciągu 10 sekund oznacza sukces.
Nieudane dostarczenie jest ponawiane przez prawie trzy dni z coraz dłuższymi przerwami. Retry-After w odpowiedzi 429 lub 503 jest respektowany; 410 wyłącza webhook; 10 kolejnych niepowodzeń wstrzymuje go do czasu wznowienia.
Dostarczenia do jednego webhooka są wysyłane ściśle po kolei. Wolny webhook nie opóźnia innych webhooków.
To samo zdarzenie może dotrzeć więcej niż raz: odrzucaj duplikaty według webhook-id.

Przewodnik Odbieraj webhooki krok po kroku buduje kompletnego odbiorcę ze sprawdzaniem podpisu w językach Node.js, Python i Go.

Zarządzaj webhookami

Czynność	Operacja
Utwórz webhook i uzyskaj jego sekret	`POST /v1/webhooks`
Zmień adres, zdarzenia lub stan	`PATCH /v1/webhooks/{webhook_id}`
Wyślij zdarzenie testowe	`POST /v1/webhooks/{webhook_id}/test`
Wymień sekret	`POST /v1/webhooks/{webhook_id}/rotate-secret`
Wznów wstrzymany webhook	`POST /v1/webhooks/{webhook_id}/resume`
Zobacz dostarczenia i odpowiedzi	`GET /v1/webhooks/{webhook_id}/deliveries`
Wyślij dostarczenie ponownie	`POST /v1/webhooks/{webhook_id}/deliveries/{delivery_id}/redeliver`

Zarządzanie webhookami wymaga klucza z rolą admin i zakresem webhooks:manage lub administratora w panelu administracyjnym. Organizacja może mieć do 20 webhooków. Webhooki są częścią planu organizacji; jeśli plan ich nie obejmuje, te operacje odpowiadają 403 z kodem webhooks.feature_disabled.