--- title: "Punkty końcowe webhooków" description: "Zarządzaj wieloma adresami URL webhooków, korzystając z sekretów i filtrów zdarzeń dla każdego punktu końcowego." --- System webhooków oparty na endpointach umożliwia zarejestrowanie **wielu** miejsc docelowych dla każdej organizacji, z których każde ma własny sekret, własny status i własną subskrypcję podzbioru typów zdarzeń. To zalecany model dla wszystkich nowych integracji. Porównaj ze [starszym webhookiem z pojedynczym adresem URL](/api-reference/organizations#legacy-single-url-webhook), który zachowano dla zgodności wstecznej, ale obsługuje tylko jeden adres URL na organizację. ## Endpointy | Metoda | Ścieżka | Wymagana rola | Opis | |--------|------|---------------|-------------| | `GET` | `/v1/developer/webhook-endpoints` | `admin+` | Wyświetl listę punktów końcowych | | `POST` | `/v1/developer/webhook-endpoints` | `admin+` | Utwórz punkt końcowy | | `PATCH` | `/v1/developer/webhook-endpoints/{endpoint_id}` | `admin+` | Zaktualizuj etykietę / URL / zdarzenia / status | | `DELETE` | `/v1/developer/webhook-endpoints/{endpoint_id}` | `admin+` | Usuń punkt końcowy | | `POST` | `/v1/developer/webhook-endpoints/{endpoint_id}/rotate-secret` | `admin+` | Zastąp sekret podpisu | | `POST` | `/v1/developer/webhook-endpoints/{endpoint_id}/test` | `admin+` | Wyślij podpisaną dostawę testową | | `GET` | `/v1/developer/webhook-deliveries` | `admin+` | Sprawdź ostatnie wyniki dostaw punktów końcowych i starszych dostaw | ## Obiekt punktu końcowego ```json { "id": "c4d5e6f7-...", "label": "Production — Call events", "url": "https://example.com/thunderphone/hook", "events": ["telephony.incoming", "telephony.complete"], "status": "active", "agent_id": 42, "agent_name": "Support Agent", "secret_hint": "a1b2…9f0e", "paused_at": null, "pause_last_error": "", "pause_undelivered_count": null, "created_at": "2026-04-20T18:24:10.113Z", "updated_at": "2026-04-20T18:24:10.113Z" } ``` | Pole | Typ | Opis | |-------|------|-------------| | `id` | UUID | Identyfikator punktu końcowego | | `label` | ciąg znaków | Nazwa wyświetlana, 1–120 znaków | | `url` | ciąg znaków | Adres URL HTTPS; `http://localhost` dozwolony w środowisku deweloperskim | | `events` | tablica ciągów znaków | Typy subskrybowanych zdarzeń (zobacz [prawidłowe wartości](#valid-event-types)). Pusta tablica subskrybuje wszystkie zdarzenia z wyjątkiem zdarzeń dla każdej tury wymagających jawnej subskrypcji (`telephony.turn` / `web.turn`) | | `status` | ciąg znaków | `active`, `disabled` (wstrzymany ręcznie) lub `failing` (ustawiany automatycznie, gdy dostarczenie wyczerpie harmonogram ponawiania przez 24 h bez ani jednej odpowiedzi 2xx) | | `agent_id` | liczba całkowita \| null | Agent, którego dotyczy ten punkt końcowy; `null` oznacza całą organizację | | `agent_name` | ciąg znaków \| null | Nazwa agenta, którego dotyczy punkt końcowy, lub `null` dla punktu końcowego obejmującego całą organizację | | `secret_hint` | ciąg znaków | Pierwsze 4 i ostatnie 4 znaki sekretu podpisywania z wielokropkiem (`a1b2…9f0e`) — wystarczające, aby porównać go z sekretem zapisanym lokalnie bez ujawniania pełnej wartości | | `paused_at` | znacznik czasu \| null | Kiedy ThunderPhone ustawił stan punktu końcowego na `failing`. `null`, gdy ma stan `active` lub `disabled` | | `pause_last_error` | ciąg znaków | Ostatni błąd dostarczenia, gdy punkt końcowy został wstrzymany, na przykład `HTTP 503: Service Unavailable`. Puste, chyba że stan to `failing` | | `pause_undelivered_count` | liczba całkowita \| null | Zdarzenia niedostarczone od ostatniego pomyślnego dostarczenia przez punkt końcowy, zliczone w chwili jego wstrzymania | | `created_at`, `updated_at` | znacznik czasu | | Pełny `secret` punktu końcowego jest zwracany **tylko raz** podczas tworzenia i nigdy więcej. Przechowuj go bezpiecznie — jeśli go utracisz, [obróć go](#rotate-the-signing-secret), aby uzyskać nowy. ### Prawidłowe typy zdarzeń `events` jest walidowane względem dokładnie tego zestawu — wartości spoza listy zwracają `400`. Zobacz [katalog zdarzeń](/pl/webhooks/events), aby poznać strukturę ładunku każdego typu. - `telephony.incoming`, `telephony.complete`, `telephony.tool`, `telephony.turn` - `web.incoming`, `web.complete`, `web.tool`, `web.turn` - `sms.sent`, `sms.failed` - `sms.received` (zarezerwowane; jeszcze nie emitowane) - `call.graded`, `call.data_extracted`, `call.transfer_completed` - `campaign.completed` - `issue.reported`, `issue.escalated` - `test-call.completed` - `alert.triggered` `issue.escalated` nie ma kontekstu agenta i jest dostarczane wyłącznie do punktów końcowych obejmujących całą organizację. Nie można wybrać jawnie `voice.ready` ani `voice.failed`. Aby je otrzymywać, utwórz punkt końcowy obejmujący całą organizację z `events: []`. Pusta lista zdarzeń odbiera każde obsługiwane zdarzenie z wyjątkiem `telephony.turn` i `web.turn`, które należy wybrać jawnie. ### Statusy punktów końcowych - `active` — dostarczanie przebiega normalnie. - `disabled` — ręcznie wstrzymany za pomocą `PATCH`. Żadne żądania nie są wysyłane. Nigdy nie zmieniamy statusu endpointu `disabled`; ponowne ustawienie go na `active` zawsze należy do Ciebie. - `failing` — ustawiany automatycznie, gdy dostarczenie do endpointu wykorzysta cały harmonogram ponownych prób (8 prób w ciągu 24 godzin), ani razu nie otrzymując kodu 2xx. Endpoint ze statusem błędu nie otrzymuje dalszego ruchu. Gdy to nastąpi, wysyłamy e-mail do właścicieli i administratorów Twojej organizacji, a panel pokazuje wstrzymany endpoint z przyciskiem Ponownie aktywuj. Po naprawieniu endpointu ustaw jego status z powrotem na `active` za pomocą `PATCH`; dostarczanie, którego harmonogram ponownych prób jeszcze nie wygasł, zostanie wznowione od miejsca, w którym zostało przerwane. --- ## Lista punktów końcowych ```bash cURL curl https://api.thunderphone.com/v1/developer/webhook-endpoints \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" ``` Zwraca tablicę [obiektów punktów końcowych](#endpoint-object). Przekaż `?agent_id=42`, aby zwrócić tylko punkty końcowe ograniczone do tego agenta. ### Punkty końcowe ograniczone do agenta Punkty końcowe obejmujące całą organizację otrzymują każde pasujące zdarzenie. Punkt końcowy z `agent_id` otrzymuje tylko pasujące zdarzenia dla połączeń obsługiwanych przez tego agenta; zdarzenia bez kontekstu agenta, takie jak `alert.triggered`, nigdy do niego nie trafiają. Te punkty końcowe możesz również tworzyć i zarządzać nimi w sekcji **Webhooki** kreatora agenta. --- ## Utwórz punkt końcowy ```bash cURL curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "label": "Production — Call events", "url": "https://example.com/thunderphone/hook", "events": ["telephony.incoming", "telephony.complete"] }' ``` ```python Python result = requests.post( "https://api.thunderphone.com/v1/developer/webhook-endpoints", headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"}, json={ "label": "Production — Call events", "url": "https://example.com/thunderphone/hook", "events": ["telephony.incoming", "telephony.complete"], }, ).json() secret = result["secret"] endpoint_id = result["id"] ``` ### Pola żądania | Pole | Typ | Wymagane | Opis | |-------|------|----------|-------------| | `label` | string | tak | 1–120 znaków | | `url` | string | tak | Adres URL HTTPS (`http` dozwolone tylko dla `localhost` / `127.0.0.1`) | | `events` | array | nie | Pusta lub pominięta wartość subskrybuje wszystkie zdarzenia z wyjątkiem `telephony.turn` / `web.turn`, które wymagają jawnej subskrypcji. Należy użyć wartości wymienionych w sekcji [Prawidłowe typy zdarzeń](#valid-event-types); duplikaty są usuwane | | `agent_id` | integer \| null | nie | Ogranicza dostarczanie do agenta w tej organizacji; pomiń lub użyj `null`, aby utworzyć punkt końcowy dla całej organizacji | Zwraca `201 Created` z [obiektem punktu końcowego](#endpoint-object) oraz dodatkowym polem `secret` najwyższego poziomu zawierającym nieprzetworzony klucz podpisywania — 48-znakowy ciąg szesnastkowy: ```json { "id": "c4d5e6f7-…", "label": "Production — Call events", "url": "https://example.com/thunderphone/hook", "events": ["telephony.incoming", "telephony.complete"], "status": "active", "secret_hint": "a1b2…9f0e", "created_at": "2026-04-20T18:24:10.113Z", "updated_at": "2026-04-20T18:24:10.113Z", "secret": "a1b2c37e08d94f5b16a2c8d90e7f3a4b5c6d7e8f90a19f0e" } ``` `secret` jest zwracane **tylko podczas tworzenia**. Kolejne odpowiedzi `GET` zawierają tylko `secret_hint`. Skopiuj pełną wartość do menedżera sekretów przed zamknięciem odpowiedzi. --- ## Zaktualizuj punkt końcowy ```bash cURL curl -X PATCH https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "label": "Production — Call + Grade events", "events": ["telephony.incoming", "telephony.complete", "call.graded"] }' ``` | Pole | Typ | Opis | |-------|------|-------------| | `label` | string | | | `url` | string | | | `events` | array | | | `status` | string | `active` lub `disabled`. Ustaw `active`, aby ponownie włączyć punkt końcowy oznaczony przez serwer jako `failing` | | `agent_id` | integer \| null | Ustaw identyfikator agenta, aby ograniczyć zakres punktu końcowego, lub `null`, aby obejmował całą organizację | Zwraca `200 OK` ze zaktualizowanym [obiektem punktu końcowego](#endpoint-object). --- ## Zmień sekret podpisu Zastąp sekret podpisu punktu końcowego, na przykład gdy został utracony lub mógł wyciec. W przypadku punktu końcowego przypisanego do agenta możesz także użyć panelu: otwórz sekcję **Webhooki** agenta i wybierz **Wygeneruj ponownie sekret** dla punktu końcowego. Punkty końcowe obejmujące całą organizację są zmieniane przez API. ```bash cURL curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../rotate-secret \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{}' ``` | Pole | Typ | Wymagane | Opis | |-------|------|----------|-------------| | `include_copies` | wartość logiczna | nie | Domyślnie `true`. Przekazuje również nowy sekret innym punktom końcowym w organizacji, które mają ten sam adres URL i ten sam bieżący sekret, takim jak kopie tego punktu końcowego na innych agentach, aby jeden odbiornik nadal weryfikował za pomocą jednego sekretu | Zwraca `200 OK`: ```json { "endpoint": { "id": "c4d5e6f7-...", "secret_hint": "7f3a…c21d", "...": "..." }, "secret": "7f3a90b2c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5c21d", "rotated_endpoint_ids": ["c4d5e6f7-..."] } ``` | Pole | Typ | Opis | |-------|------|-------------| | `endpoint` | obiekt | [Obiekt punktu końcowego](#endpoint-object) z nowym `secret_hint` | | `secret` | ciąg znaków | Nowy sekret podpisu. Zwracany tylko w tej odpowiedzi | | `rotated_endpoint_ids` | tablica UUID | Każdy punkt końcowy, który teraz używa nowego sekretu | Stary sekret przestaje być używany natychmiast: kolejne dostarczenie, w tym ponowne próby, jest podpisywane nowym sekretem. Dopóki odbiornik nie ma nowego sekretu, dostarczenia nie przechodzą kontroli podpisu; jeśli odpowie na nie statusem innym niż 2xx, są ponawiane zgodnie ze standardowym 24 h harmonogramem, dlatego niezwłocznie zaktualizuj odbiornik. Jeśli wdrażanie odbiornika odbywa się etapami, podczas wdrażania powinien akceptować oba sekrety — pomocnicze funkcje weryfikacji SDK przyjmują listę sekretów (zobacz [Weryfikowanie podpisów webhooków](/pl/guides/verify-webhook-signatures)). --- ## Wyślij testowe dostarczenie Wyślij syntetyczne zdarzenie `webhook.test` do jednego punktu końcowego, korzystając ze standardowego potoku dostarczania, w tym kanonicznej serializacji JSON, obu nagłówków podpisu, rejestrowania dostarczenia i obsługi ponownych prób. Test jest kierowany do wybranego punktu końcowego niezależnie od jego filtra `events`. ```bash cURL curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" ``` Punkt końcowy otrzymuje otoczkę podobną do tej: ```json { "data": { "message": "ThunderPhone webhook test", "sent_at": "2026-07-17T20:12:34.567890+00:00" }, "event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1", "type": "webhook.test" } ``` API zwraca `200 OK` po pierwszej próbie, nawet jeśli miejsce docelowe zwróci błąd. Sprawdź `success`, `status`, `response_code` i `error`, aby poznać wynik dostarczenia: ```json { "success": true, "event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1", "event_type": "webhook.test", "status": "delivered", "response_code": 204, "error": "" } ``` `webhook.test` jest syntetyczne i nie można go dodać do subskrypcji `events` punktu końcowego. Jeśli pierwsza próba się nie powiedzie, ThunderPhone ponowi ją raz po około minucie, a następnie zakończy; dostarczenie będzie wtedy mieć `status: "failed"` w sekcji [Debugowanie dostarczeń](#debug-deliveries). Testowe dostarczenie nigdy nie oznacza punktu końcowego jako `failing`. Aby skonfigurować wyzwalacz dla rzeczywistego formatu zdarzenia, przekaż opcjonalny `event_type`. Dostarczenie nadal jest syntetyczne i zawiera `"sample": true`; próbki związane z połączeniami używają `call_id: 0` i `agent_id: 0`. ```bash curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"event_type":"call.graded"}' ``` `event_type` akceptuje dowolną wartość z listy [Prawidłowe typy zdarzeń](#valid-event-types). Pominięcie go zachowuje ogólne zachowanie `webhook.test`. --- ## Usuń punkt końcowy ```bash cURL curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" ``` Zwraca `204 No Content`. Dostarczanie na ten URL zostaje natychmiast zatrzymane; trwające ponowienia są anulowane. --- ## Debugowanie dostarczeń Zanim uznasz, że webhook nie został wysłany, sprawdź [`GET /v1/developer/webhook-deliveries`](/api-reference/webhook-deliveries). Wyświetla ostatnie próby z obu systemów webhooków, w tym identyfikator połączenia, pochodzenie URL, status HTTP, liczbę prób, kategorię błędu z listy dozwolonych oraz czas następnego ponowienia. Nigdy nie zwraca ładunku zdarzenia, transkrypcji, zapisanego tekstu błędu, treści odpowiedzi ani ścieżki URL. Tę samą ostatnią historię możesz również zobaczyć w **Agenci → wybierz agenta → Webhooki → Ostatnie dostarczenia**. Wiersze pokazują etykietę punktu końcowego oraz pochodzenie URL użyte w najnowszej próbie. Jest to stan operacyjny, a nie niezmienny dziennik audytowy: usunięcie punktu końcowego usuwa również jego wiersze dostarczeń. W przypadku błędu `404` w n8n najpierw potwierdź, że przepływ pracy jest aktywny, akceptuje `POST` i używa produkcyjnego URL webhooka zamiast URL testowego. Błąd `401` lub `403` wskazuje na uwierzytelnianie lub weryfikację podpisu; przekroczenia limitu czasu wskazują na opóźnienia lub dostępność miejsca docelowego; błędy TLS wskazują na łańcuch certyfikatów, nazwę hosta lub datę wygaśnięcia. --- ## Powiązane Pełna lista wartości `events`, które możesz subskrybować. Weryfikacja podpisu i semantyka dostarczania.