Przejdź do treści
Sursa Developers

POST/v1/webhooks/{webhook_id}/test

Wysyłanie zdarzenia testowego

test_webhook

Wysyła zdarzenie natychmiast, niezależnie od subskrypcji i stanu webhooka, z test: true, poza kolejnością dostarczeń webhooka i bez X-KB-Sequence. Zdarzenie nie jest zapisywane w kanale zdarzeń. type to dowolny typ z katalogu (domyślnie webhook.ping); data pochodzi z przykładu zdarzenia w sekcji webhooks specyfikacji. Niepowodzenie nie jest ponawiane i nie wlicza się do progu wstrzymania. Odpowiedzią jest dostarczenie z kodem odpowiedzi odbiorcy i błędem.

Uwierzytelnianie

Wyślij klucz API w nagłówku Authorization: Authorization: Bearer <klucz>.

Parametry ścieżki

  • webhook_idintegerwymagane

Parametry nagłówka

  • Idempotency-Keystring

    Klucz bezpiecznego ponowienia zapisu: od 1 do 255 drukowalnych znaków ASCII; zalecany jest UUID v4 na każdą operację logiczną. Ponowienie z tym samym kluczem w ciągu 24 godzin nie wykonuje operacji ponownie: zwraca zapisaną odpowiedź (status, nagłówki i treść) z nagłówkiem Idempotency-Replayed: true. Ten sam klucz z inną metodą, ścieżką, Content-Type lub treścią zwraca 409 api.idempotency_mismatch; dopóki pierwsze żądanie jest jeszcze wykonywane – 409 api.idempotency_in_progress z Retry-After: 1. Po odpowiedzi 5xx lub 429 klucz zostaje zwolniony, a ponowienie wykonuje operację jeszcze raz. Klucz obowiązuje w obrębie organizacji i wywołującego (klucz API, użytkownik lub klucz własnego źródła).

    length ≥ 1, length ≤ 255

Treść żądania

application/json

Obiekt: WebhookTestRequest

Odpowiedzi

200Podjęto próbę dostarczenia (czy się powiodła – podaje `status`).

Nagłówki odpowiedzi

  • RateLimit-Policy

    Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.

  • RateLimit

    Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).

  • X-RateLimit-Remaining

    Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.

  • X-RateLimit-Reset

    Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.

  • Idempotency-Replayed

    true oznacza, że odpowiedź została odtworzona z odpowiedzi zapisanej dla tego Idempotency-Key: operacja nie została wykonana ponownie.

application/json

Obiekt: WebhookDelivery

  • expandedWebhookDeliveryExpanded
  • idintegerwymagane
  • webhook_idintegerwymagane
  • event_idstringwymagane

    ID zdarzenia (evt_…), wysyłany także w nagłówku X-KB-Event-Id i w treści dostarczenia.

  • event_typeWebhookEventTypewymagane
  • event_created_atstring (date-time)wymagane
  • attemptintegerwymagane

    Liczba wykonanych prób.

  • statusWebhookDeliveryStatuswymagane
  • response_codeinteger | null
  • duration_msinteger | null
  • next_retry_atstring (date-time) | null
  • errorstring | null
  • delivered_atstring (date-time) | null
  • created_atstring (date-time)wymagane
  • updated_atstring (date-time)wymagane
  • sequenceinteger | null

    Numer w kolejności dostarczeń webhooka (X-KB-Sequence); null dla dostarczenia testowego.

  • testbooleanwymagane

    Dostarczenie testowe (POST /v1/webhooks/{webhook_id}/test).

  • redelivery_ofinteger | null

    Pierwotne dostarczenie, jeśli to dostarczenie jest ponowne.

  • error_codestring | null

    Kod neutralny ostatniego niepowodzenia: timeout, connection_failed, tls_error, private_address, unresolvable, redirect, http_error, request_failed, endpoint_disabled, event_expired; anulowane dostarczenie (cancelled) może mieć też event_not_permitted (w chwili próby zdarzenie wykracza poza uprawnienia webhooka, ponieważ uprawnienia zawężono po rozesłaniu zdarzenia) lub event_unavailable (treść dostarczenia testowego nie jest już dostępna).

401Nie przesłano danych uwierzytelniających (ani pliku cookie sesji, ani klucza API) lub nie znaleziono klucza.

Nagłówki odpowiedzi

  • RateLimit-Policy

    Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.

  • RateLimit

    Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).

  • X-RateLimit-Remaining

    Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.

  • X-RateLimit-Reset

    Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.

application/json

Obiekt: Error

403Działanie jest niedozwolone: rola jest niewystarczająca, brak dostępu do kolekcji lub karty, żądanie jest wykonywane w trybie „View as” albo organizacja jest zawieszona lub usunięta (`detail` to obiekt z `code: org_suspended | org_deleted`).

Nagłówki odpowiedzi

  • RateLimit-Policy

    Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.

  • RateLimit

    Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).

  • X-RateLimit-Remaining

    Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.

  • X-RateLimit-Reset

    Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.

application/json

Obiekt: Error

404Obiekt nie istnieje lub nie jest dla Ciebie dostępny. API nie potwierdza istnienia obiektu z ograniczonym dostępem.

Nagłówki odpowiedzi

  • RateLimit-Policy

    Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.

  • RateLimit

    Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).

  • X-RateLimit-Remaining

    Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.

  • X-RateLimit-Reset

    Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.

application/json

Obiekt: Error

429Zbyt wiele żądań (`api.rate_limited`), wyczerpano przydział organizacji na minutę, dzień lub miesiąc (`api.quota_exceeded`; `error.details` zawiera `quota`, `limit` i `reset_at`), osiągnięto limit organizacji albo usługa odpowiedzi jest zajęta (`answers.engine_busy`). Odczekaj czas podany w nagłówku `Retry-After`.

Nagłówki odpowiedzi

  • Retry-After

    Liczba sekund oczekiwania przed ponowieniem żądania.

  • RateLimit-Policy

    Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.

  • RateLimit

    Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).

  • X-RateLimit-Remaining

    Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.

  • X-RateLimit-Reset

    Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.

application/json

Obiekt: Error

Kody błędów

Kody, które ta operacja może zwrócić w error.code, oprócz ogólnych kodów każdego żądania.

Bezpieczne ponawianie

Wysyłaj nagłówek Idempotency-Key (na przykład UUID) z każdym żądaniem POST i PATCH. Ponowienie z tym samym kluczem w ciągu 24 godzin zwraca zapisaną odpowiedź, zamiast ponownie wykonywać żądanie.

Limity częstotliwości

Odpowiedzi zawierają nagłówki RateLimit i RateLimit-Policy oraz starsze X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset. Odpowiedź 429 ma nagłówek Retry-After w sekundach: odczekaj i ponów żądanie.

← webhooks · Dokumentacja API