API Webhooków

Webhooki pozwalają platformie powiadamiać Twoje inne systemy w momencie, gdy coś się wydarzy — nowy kontakt, odpowiedź, umówione spotkanie i nie tylko. To API zarządza samymi subskrypcjami: które adresy URL otrzymują które zdarzenia. Informacje o tym, jak odbierać i weryfikować ładunki (payloads) otrzymywane przez Twój punkt końcowy, znajdziesz w sekcji Webhooki.

Wszystkie poniższe ścieżki są względne względem bazowego adresu URL API:

https://api.youraiconnector.com/v1

Każde żądanie musi zostać uwierzytelnione. Zobacz Uwierzytelnianie, aby poznać cztery akceptowane metody. Przykłady tutaj używają nagłówka X-API-Key (oraz jednej formy parametru zapytania dla cURL).

Uwaga: Webhooki muszą być włączone dla Twojego konta. Jeśli nie są, te punkty końcowe zwrócą 403.

Jak adresowane są subskrypcje

Każda subskrypcja posiada id oraz opcjonalną name. Każde z nich może być użyte jako {webhookId} w ścieżce do aktualizacji, usunięcia, testowania, sprawdzania stanu i ponownego włączenia.

Preferuj nazwę. Identyfikatory subskrypcji są pozycyjne, więc mogą ulec zmianie po usunięciu innej subskrypcji. Jeśli podczas tworzenia subskrypcji ustawisz stałą name, adresuj ją za pomocą nazwy, aby uniknąć niespodzianek.

Lista subskrypcji

GET /webhooks

cURL

curl "https://api.youraiconnector.com/v1/webhooks?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/webhooks", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/webhooks",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Odpowiedź

{
  "success": true,
  "webhooks": [
    {
      "id": "0",
      "name": "Order updates hook",
      "url": "https://hooks.example.com/incoming",
      "subscribed_to": ["Contact Created", "Replies"],
      "subscribed_to_tags": [],
      "created_at": "2026-06-09T12:00:00.000Z",
      "signing_enabled": true,
      "signing_secret_created_at": "2026-07-15T09:30:00.000Z",
      "retries_enabled": true,
      "enabled": true,
      "apply_to_sub_accounts": false
    }
  ]
}

signing_enabled oraz retries_enabled to opcje włączane dla każdej subskrypcji z osobna; obie są domyślnie wyłączone, dopóki ich nie włączysz. Zobacz Podpisane ładunki oraz Ponowne próby.

apply_to_sub_accounts to opcja dziedziczenia przez agencję — zobacz Jedna subskrypcja dla wszystkich kont klientów. Domyślnie wyłączona i nieaktywna na kontach, które nie posiadają kont klientów.

enabled to przełącznik włączania/wyłączania subskrypcji — zobacz Wyłączanie subskrypcji. Wyłączone subskrypcje są nadal tutaj wyświetlane.

Sam sekret podpisywania nigdy nie jest tutaj uwzględniany — odczytaj go z GET /webhooks/{id}/signing-secret.

Lista subskrybowalnych typów zdarzeń

Zwraca dokładne ciągi znaków, których możesz użyć w subscribed_to. Użyj tego, aby odkryć poprawne nazwy zdarzeń zamiast wpisywać je na sztywno w kodzie.

GET /webhooks/events

cURL

curl "https://api.youraiconnector.com/v1/webhooks/events" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/webhooks/events", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/webhooks/events",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Odpowiedź

Odpowiedź to {"success": true, "events": [...]}, gdzie events zawiera obecnie 22 dokładne ciągi znaków: Contact Created, Human Alerted, Appointment Booked, Replies, Reads, Deliveries, Credits Spent, Credits Recharged, Low Credit Balance, Contact Paused, Contact Do Not Disturb, Contact Unarchived, New Message, Contact Resumed, Chat Concluded, Task Created, Task Updated, Task Completed, Daily Summary Created, Channel Connected, Broadcast Started oraz Broadcast Completed (Channel Connected jest akceptowane w subscribed_to, ale obecnie nic go nie emituje, więc nie należy na nim polegać).

Aby dowiedzieć się, co oznacza każde zdarzenie i jaki kod event wysyła w ładunku (payload), zobacz 22 zdarzenia webhooka. Ten punkt końcowy jest w każdej chwili wiarygodną listą — odczytuj ją na żywo, zamiast wpisywać nazwy na sztywno w kodzie.

Utwórz subskrypcję

POST /webhooks

Pole	Wymagane	Opis
`url`	Tak	Adres URL HTTPS, który będzie otrzymywać ładunki zdarzeń przez `POST`. Musi być publicznie dostępny.
`subscribed_to`	Tak	Niepusta tablica nazw zdarzeń (zobacz `/webhooks/events`).
`name`	Nie	Nazwa wyświetlana. Można jej później użyć jako `{webhookId}`. Domyślnie jest to nazwa z sygnaturą czasową.
`subscribed_to_tags`	Nie	Identyfikatory tagów, które zawężają, które tagi generują powiadomienie o podsumowaniu rozmowy. Nie ogranicza to zdarzeń subskrypcji do tych tagów — aby otrzymać żądanie po zastosowaniu określonego tagu, ustaw adres URL webhooka dla tego tagu w zakładce Tagi agenta (lub kampanii).
`retries_enabled`	Nie	Wartość logiczna, domyślnie `false`. Wyrażenie zgody na ponowne próby dostarczenia w przypadku niepowodzenia.
`generate_signing_secret`	Nie	Wartość logiczna, domyślnie `false`. Wygeneruj klucz tajny podpisu HMAC wraz z subskrypcją. Klucz tajny jest zwracany jednorazowo jako `signing_secret` najwyższego poziomu w odpowiedzi.
`enabled`	Nie	Wartość logiczna, domyślnie `true`. Przekaż `false`, aby utworzyć wyłączoną subskrypcję. Zobacz Wyłączanie subskrypcji.
`apply_to_sub_accounts`	Nie	Wartość logiczna, domyślnie `false`. Na koncie agencji `true` sprawia, że ta subskrypcja otrzymuje również zdarzenia z każdego konta klienta — zobacz Jedna subskrypcja dla wszystkich kont klientów.

Zasady dotyczące adresu URL: Adres URL musi używać https:// i być publicznie dostępny. Zwykły http://, localhost, adresy sieci prywatnych oraz adresy wewnętrzne platformy są odrzucane z błędem 400.

cURL

curl -X POST "https://api.youraiconnector.com/v1/webhooks?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/incoming",
    "subscribed_to": ["Contact Created", "Replies"],
    "name": "Order updates hook"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/webhooks", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://hooks.example.com/incoming",
    subscribed_to: ["Contact Created", "Replies"],
    name: "Order updates hook",
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/webhooks",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "url": "https://hooks.example.com/incoming",
        "subscribed_to": ["Contact Created", "Replies"],
        "name": "Order updates hook",
    },
)
data = res.json()

Odpowiedź

{
  "success": true,
  "webhook_id": "1",
  "webhook": {
    "id": "1",
    "name": "Order updates hook",
    "url": "https://hooks.example.com/incoming",
    "subscribed_to": ["Contact Created", "Replies"],
    "subscribed_to_tags": [],
    "created_at": "2026-06-09T12:00:00.000Z"
  }
}

Zaktualizuj subskrypcję

Podaj co najmniej jedno z pól: url, subscribed_to, name, subscribed_to_tags, retries_enabled, enabled lub apply_to_sub_accounts. Pominięte pola zachowują swoje bieżące wartości. subscribed_to i subscribed_to_tags to zastąpienia, a nie scalenia.

PUT /webhooks/{webhookId}

Aktualizacja subskrypcji nigdy nie narusza jej klucza tajnego podpisu — zarządzaj nim poprzez trasy klucza tajnego podpisu.

Gdy adres URL ulegnie zmianie, dostarczanie dla nowego adresu URL zostanie automatycznie włączone ponownie, co daje wcześniej niedziałającemu punktowi końcowemu nowy start.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/webhooks/Order%20updates%20hook" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/v2/incoming",
    "subscribed_to": ["Replies", "Chat Concluded"]
  }'

JavaScript

const res = await fetch(
  `https://api.youraiconnector.com/v1/webhooks/${encodeURIComponent("Order updates hook")}`,
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      url: "https://hooks.example.com/v2/incoming",
      subscribed_to: ["Replies", "Chat Concluded"],
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/webhooks/Order updates hook",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "url": "https://hooks.example.com/v2/incoming",
        "subscribed_to": ["Replies", "Chat Concluded"],
    },
)
data = res.json()

Odpowiedź

{
  "success": true,
  "webhook_id": "0",
  "webhook": {
    "id": "0",
    "name": "Order updates hook",
    "url": "https://hooks.example.com/v2/incoming",
    "subscribed_to": ["Replies", "Chat Concluded"],
    "subscribed_to_tags": [],
    "created_at": "2026-06-09T12:00:00.000Z"
  }
}

Nieznany identyfikator lub nazwa zwraca 404 z { "success": false, "error": "Webhook not found" }.

Usuń subskrypcję

Usuwa subskrypcję, dzięki czemu jej adres URL przestaje otrzymywać ładunki. Liczniki stanu dostarczania są resetowane, więc ponowne dodanie tego samego adresu URL później rozpocznie się z czystą kartą.

DELETE /webhooks/{webhookId}

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/webhooks/0" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/webhooks/0", {
  method: "DELETE",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/webhooks/0",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Odpowiedź

{
  "success": true
}

Wyślij testowy ładunek

Wysyła przykładowy ładunek na adres URL subskrypcji, aby umożliwić weryfikację odbiorcy w modelu end-to-end. Opcjonalnie przekaż event, aby określić, jaki typ zdarzenia ma symulować próbka. Testowe dostarczenia nigdy nie wpływają na liczniki kondycji subskrypcji.

POST /webhooks/{webhookId}/test

Odpowiedź zawsze zwraca 200 i raportuje wynik za pomocą flagi delivered — nieudany test nie zwraca statusu błędu. Gdy delivered ma wartość false, odpowiedź zawiera szczegóły błędu.

Pole	Wymagane	Opis
`event`	Nie	Typ zdarzenia do symulacji (musi być jednym z `/webhooks/events`). Domyślnie jest to zdarzenie dostarczenia.

cURL

curl -X POST "https://api.youraiconnector.com/v1/webhooks/0/test?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "event": "Contact Created" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/webhooks/0/test", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ event: "Contact Created" }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/webhooks/0/test",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"event": "Contact Created"},
)
data = res.json()

Odpowiedź (dostarczono)

{
  "success": true,
  "webhook_id": "0",
  "delivered": true
}

Odpowiedź (niepowodzenie)

{
  "success": true,
  "webhook_id": "0",
  "delivered": false,
  "failure_type": "permanent",
  "status_code": 404,
  "error_message": "Request failed with status code 404"
}

failure_type jest jednym z permanent, temporary, timeout, network lub unknown.

Sprawdź kondycję dostarczania

Zwraca rekord kondycji dostarczania dla adresu URL subskrypcji: ile dostarczeń zakończyło się powodzeniem, a ile niepowodzeniem, czy dostarczanie jest obecnie wstrzymane po wielokrotnych błędach oraz szczegóły ostatniego niepowodzenia. Zwraca "health": null, jeśli nie podjęto jeszcze żadnych prób dostarczenia.

GET /webhooks/{webhookId}/health

cURL

curl "https://api.youraiconnector.com/v1/webhooks/0/health" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/webhooks/0/health", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/webhooks/0/health",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Odpowiedź

{
  "success": true,
  "webhook_id": "0",
  "url": "https://hooks.example.com/incoming",
  "health": {
    "consecutive_failures": 0,
    "total_failures": 2,
    "total_successes": 120,
    "is_disabled": false,
    "disabled_at": null,
    "disabled_reason": null,
    "last_failure": null,
    "last_success_at": "2026-06-09T12:00:00.000Z",
    "created_at": "2026-05-01T08:00:00.000Z",
    "updated_at": "2026-06-09T12:00:00.000Z"
  }
}

Gdy is_disabled ma wartość true, dostarczanie pod adres URL zostało automatycznie wstrzymane po wielokrotnych błędach. Napraw odbiornik, a następnie włącz go ponownie (poniżej).

Ponowne włączenie dostarczania

Wznawia dostarczanie dla webhooka, którego adres URL został automatycznie wstrzymany po wielokrotnych błędach. Resetuje to flagę wstrzymania oraz liczniki błędów, ale nie podejmuje próby dostarczenia — użyj punktu końcowego testu, aby potwierdzić, że odbiornik znów działa poprawnie.

POST /webhooks/{webhookId}/reenable

cURL

curl -X POST "https://api.youraiconnector.com/v1/webhooks/0/reenable?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/webhooks/0/reenable", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/webhooks/0/reenable",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Odpowiedź

{
  "success": true,
  "webhook_id": "0"
}

Wyłączanie subskrypcji

enabled to własny przełącznik włączania/wyłączania subskrypcji. Wyłączenie go zatrzymuje dostawy, zachowując jednocześnie adres URL, listę zdarzeń i klucz tajny podpisywania.

# Off
curl -X PUT "https://api.youraiconnector.com/v1/webhooks/0?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

# Back on
curl -X PUT "https://api.youraiconnector.com/v1/webhooks/0?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

Brak oznacza włączone. Subskrypcja utworzona przed wprowadzeniem tego pola nie ma zapisanej wartości enabled i działa normalnie. GET /webhooks zawsze zwraca konkretną wartość logiczną.
Wyłączone subskrypcje są nadal wyświetlane przez GET /webhooks — w ten sposób można je znaleźć, aby ponownie je włączyć.
Ponowna próba zakolejkowana przed wyłączeniem nie zostanie wznowiona: ponowna próba odczytuje subskrypcję w momencie wysyłki i zostaje odrzucona, jeśli subskrypcja jest wyłączona.
Nic, co zostało pominięte podczas wyłączenia, nie zostanie ponownie wysłane po ponownym włączeniu.

Różni się od automatycznego wyłączenia po wielokrotnych awariach, które jest zgłaszane przez GET /webhooks/{id}/health jako is_disabled i usuwane za pomocą POST /webhooks/{id}/reenable. enabled to przełącznik konta; is_disabled to nasz. Żaden z nich nie nadpisuje drugiego — aby dostawa mogła zostać zrealizowana, subskrypcja musi być zarówno włączona, jak i nie być automatycznie wyłączona.

Jedna subskrypcja dla wszystkich kont klientów (agencje)

Na koncie agencji ustaw apply_to_sub_accounts: true w subskrypcji (podczas tworzenia lub przez PUT), a będzie ona otrzymywać również zdarzenia, które mają miejsce na każdym z kont klientów agencji — jeden punkt końcowy obsługuje całą agencję, zamiast tworzyć subskrypcję osobno na każdym koncie klienta.

curl -X PUT "https://api.youraiconnector.com/v1/webhooks/0?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"apply_to_sub_accounts": true}'

Jak to działa:

Blok user pozwala rozróżnić konta. Blok user w każdym ładunku identyfikuje konto, na którym faktycznie wystąpiło zdarzenie, dzięki czemu odbiorca może kierować ruch dla poszczególnych klientów.
Własne ustawienia subskrypcji agencji mają zastosowanie wszędzie. Jej lista zdarzeń, klucz tajny podpisu oraz opcja ponownych prób są używane również dla dziedziczonych dostarczeń.
Własna subskrypcja konta klienta do tego samego adresu URL ma pierwszeństwo. Jeśli konto klienta posiada własną subskrypcję wskazującą na ten sam adres URL, jest ona używana dla zdarzeń tego konta — to samo zdarzenie nigdy nie jest dostarczane dwukrotnie do jednego punktu końcowego.
Konta klientów tego nie widzą. Dziedziczone subskrypcje nie pojawiają się na liście webhooków konta klienta, a klient nie może ich wyłączyć — zarządza nimi wyłącznie agencja.
Stan dostarczania jest śledzony dla każdego konta klienta z osobna. Punkt końcowy, który ciągle zawodzi, jest automatycznie wyłączany dla konta, którego dostarczenia się nie powiodły, a nie dla całej agencji.
subscribed_to_tags nie podlega dziedziczeniu. Lista tagów odnosi się do własnych tagów agencji, które nie istnieją na kontach klientów — zawężanie podsumowania rozmowy dotyczy tylko własnych zdarzeń agencji.
Nieaktywne w innych przypadkach. Na koncie, które nie posiada kont klientów, flaga jest poprawnie zapisywana, ale nie wykonuje żadnej akcji.

Nagłówki przy każdym dostarczeniu

Te trzy nagłówki są wysyłane przy każdym dostarczeniu, niezależnie od tego, czy subskrypcja jest podpisana, czy nie:

Nagłówek	Znaczenie
`X-Webhook-Delivery`	Stały identyfikator zdarzenia logicznego. Identyczny przy ponownych próbach — użyj go do deduplikacji.
`X-Webhook-Attempt`	Numer próby (liczony od 1).
`X-Webhook-Event`	Nazwa zdarzenia.

Podpisane ładunki

Podpisywanie jest opcjonalne, domyślnie wyłączone i ustawiane dla każdej subskrypcji z osobna. Gdy subskrypcja posiada klucz tajny podpisu, każde dostarczenie zawiera dwa dodatkowe nagłówki oprócz trzech wysyłanych standardowo (X-Webhook-Delivery, X-Webhook-Attempt oraz X-Webhook-Event):

Nagłówek	Znaczenie
`X-Webhook-Signature`	`v1=<hex>` — HMAC-SHA256 ciągu znaków `"<timestamp>.<raw request body>"`, zakodowany kluczem tajnym webhooka, który generujesz i rotujesz w `GET/POST/DELETE /v1/webhooks/{webhookId}/signing-secret`.
`X-Webhook-Timestamp`	Czas wysłania w sekundach Unix. Powiązany z podpisem, więc nie można go niezależnie zmienić.

Aby zweryfikować, oblicz ponownie HMAC-SHA256 dla surowej treści (raw body) za pomocą swojego klucza tajnego i porównaj go z nagłówkiem. Weryfikację przeprowadzaj względem surowej treści żądania. Ponowna serializacja przetworzonego JSON-a zmienia bajty i uniemożliwia porównanie. Odrzucaj dostarczenia, których sygnatura czasowa wykracza poza okno świeżości (300 sekund to rozsądna wartość domyślna), aby zapobiec atakom typu replay, i porównuj za pomocą funkcji odpornej na ataki czasowe (timing-safe).

Zobacz Podpisane ładunki, aby uzyskać pełne przykłady weryfikacji w Node i Pythonie.

Podpisywanie to nie to samo co uwierzytelnianie API. Samo API REST uwierzytelnia się za pomocą kluczy API, a nie OAuth (OAuth 2.1 istnieje dla serwerów MCP rejestrowanych jako narzędzia bota), i nie ma jeszcze oficjalnych pakietów SDK dla npm lub PyPI — wywołuj punkty końcowe za pomocą dowolnego klienta HTTP.

Odczytaj klucz tajny podpisywania

GET /webhooks/{id}/signing-secret

curl "https://api.youraiconnector.com/v1/webhooks/0/signing-secret?apiKey=YOUR_API_KEY"

Odpowiedź

{
  "success": true,
  "webhook_id": "0",
  "signing_enabled": true,
  "signing_secret": "whsec_1a2b3c...",
  "signing_secret_created_at": "2026-07-15T09:30:00.000Z"
}

Gdy podpisywanie jest wyłączone, signing_enabled to false, a signing_secret to null.

Wygeneruj lub obróć klucz tajny podpisywania

POST /webhooks/{id}/signing-secret

Tworzy klucz tajny (włączając podpisywanie) lub zastępuje istniejący. Zwraca nowy klucz tajny.

curl -X POST "https://api.youraiconnector.com/v1/webhooks/0/signing-secret?apiKey=YOUR_API_KEY"

Odpowiedź

{
  "success": true,
  "webhook_id": "0",
  "signing_enabled": true,
  "signing_secret": "whsec_9f8e7d...",
  "signing_secret_created_at": "2026-07-15T10:00:00.000Z"
}

Rotacja wchodzi w życie natychmiast — kolejna dostawa jest podpisywana tylko nowym kluczem tajnym. Akceptuj oba klucze przez krótki czas, podczas gdy wdrażasz zmianę w aktywnym punkcie końcowym.

Możesz również utworzyć sekret w momencie tworzenia, przekazując "generate_signing_secret": true do POST /webhooks; odpowiedź zawiera wtedy pole najwyższego poziomu signing_secret.

Wyłączanie podpisywania

DELETE /webhooks/{id}/signing-secret

curl -X DELETE "https://api.youraiconnector.com/v1/webhooks/0/signing-secret?apiKey=YOUR_API_KEY"

Odpowiedź

{
  "success": true,
  "webhook_id": "0",
  "signing_enabled": false
}

Wszystkie trzy ścieżki dotyczące sekretu podpisywania wymagają uprawnienia edit (edycja) dla integracji, w tym GET — sekret jest poświadczeniem, które może służyć do fałszowania dostaw, dlatego nie jest udostępniany rolom z uprawnieniami tylko do odczytu.

Ponowne próby

Opcjonalne, domyślnie wyłączone i ustawiane dla każdej subskrypcji za pomocą wartości logicznej retries_enabled w POST /webhooks lub PUT /webhooks/{id}.

curl -X PUT "https://api.youraiconnector.com/v1/webhooks/0?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"retries_enabled": true}'

Po włączeniu nieudana dostawa jest ponawiana po 1 min, 5 min, 30 min i 2 godz. od pierwszej próby (łącznie około 2 godz. 40 min).

Ponawiane: odpowiedzi 5xx, przekroczenia limitu czasu i błędy połączenia.
Nieponawiane: wszelkie błędy 4xx. Odbiorca odrzuca samo żądanie, więc ponowne wysłanie go w niezmienionej formie tylko powieli odrzucenie.

Ponowne próby umożliwiają duplikowanie dostaw — punkt końcowy, który przetworzył zdarzenie, ale przekroczył limit czasu przed wysłaniem odpowiedzi, otrzyma je ponownie. Wykonaj deduplikację na podstawie X-Webhook-Delivery, który jest stały dla wszystkich prób. Dlatego ponowne próby są opcjonalne.

Liczniki delivery-health zliczają całą dostawę, a nie każdą próbę: błąd jest rejestrowany dopiero po wyczerpaniu wszystkich ponownych prób, więc włączenie ponownych prób nie powoduje wcześniejszego wyzwolenia automatycznego wyłączenia.

Błędy

Wszystkie błędy korzystają ze standardowej koperty:

{
  "success": false,
  "error": "Webhook not found"
}

Typowe przypadki: niedozwolony adres URL, pusty/nieprawidłowy subscribed_to lub brakujące pola zwracają 400; nieznany identyfikator lub nazwa zwracają 404; a 403 oznacza, że webhooki nie są włączone dla Twojego konta. Zobacz Błędy, aby uzyskać pełną listę.

Następne kroki

Webhooki (odbieranie ładunków) — skonfiguruj odbiornik i zrozum strukturę ładunku.
Uwierzytelnianie — cztery sposoby uwierzytelniania żądania.
Błędy i limity szybkości — kody stanu i limit 300 żądań/min.

API Webhooków #

Jak adresowane są subskrypcje #

Lista subskrypcji #

Lista subskrybowalnych typów zdarzeń #

Utwórz subskrypcję #

Zaktualizuj subskrypcję #

Usuń subskrypcję #

Wyślij testowy ładunek #

Sprawdź kondycję dostarczania #

Ponowne włączenie dostarczania #

Wyłączanie subskrypcji #

Jedna subskrypcja dla wszystkich kont klientów (agencje) #

Nagłówki przy każdym dostarczeniu #

Podpisane ładunki #

Odczytaj klucz tajny podpisywania #

Wygeneruj lub obróć klucz tajny podpisywania #

Wyłączanie podpisywania #

Ponowne próby #

Błędy #

Następne kroki #

API Webhooków

Jak adresowane są subskrypcje

Lista subskrypcji

Lista subskrybowalnych typów zdarzeń

Utwórz subskrypcję

Zaktualizuj subskrypcję

Usuń subskrypcję

Wyślij testowy ładunek

Sprawdź kondycję dostarczania

Ponowne włączenie dostarczania

Wyłączanie subskrypcji

Jedna subskrypcja dla wszystkich kont klientów (agencje)

Nagłówki przy każdym dostarczeniu

Podpisane ładunki

Odczytaj klucz tajny podpisywania

Wygeneruj lub obróć klucz tajny podpisywania

Wyłączanie podpisywania

Ponowne próby

Błędy

Następne kroki