Punkty końcowe webhooków

System webhooków oparty na punktach końcowych pozwala zarejestrować wiele miejsc docelowych na organizację, z których każde ma własny sekret, własny status i własną subskrypcję podzbioru typów zdarzeń. Jest to zalecany model dla wszystkich nowych integracji. Porównaj ze starszym webhookiem z jednym adresem URL, który jest zachowany dla zgodności wstecznej, ale obsługuje tylko jeden adres URL na organizację.

Punkty końcowe

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}/test`	`admin+`	Wyślij podpisane dostarczenie testowe

Obiekt punktu końcowego

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

Pole	Typ	Opis
`id`	UUID	Identyfikator punktu końcowego
`label`	string	Nazwa wyświetlana, 1–120 znaków
`url`	string	Adres URL HTTPS; `http://localhost` dozwolony w środowisku deweloperskim
`events`	array of string	Typy subskrybowanych zdarzeń (zobacz prawidłowe wartości). Pusta tablica subskrybuje wszystkie zdarzenia
`status`	string	`active`, `disabled` (wstrzymany ręcznie) lub `failing` (ustawiany automatycznie, gdy dostarczenie wyczerpie 24-godzinny harmonogram ponawiania bez ani jednej odpowiedzi 2xx)
`secret_hint`	string	Pierwsze 4 i ostatnie 4 znaki sekretu podpisywania z wielokropkiem (`a1b2…9f0e`) — wystarczające do porównania z sekretem zapisanym lokalnie bez ujawniania pełnej wartości
`created_at`, `updated_at`	timestamp

Pełny secret punktu końcowego jest zwracany tylko raz podczas tworzenia i nigdy więcej. Przechowuj go bezpiecznie — jeśli go utracisz, usuń punkt końcowy i utwórz go ponownie.

Prawidłowe typy zdarzeń

events jest walidowane względem dokładnie tego zestawu — wartości spoza listy zwracają 400. Zobacz Katalog zdarzeń, aby poznać strukturę ładunku każdego typu.

telephony.incoming, telephony.complete, telephony.tool
web.incoming, web.complete, web.tool
call.graded
issue.reported
test-call.completed
alert.triggered

Statusy punktów końcowych

active — dostarczenia przebiegają normalnie.
disabled — ręcznie wstrzymany przez PATCH. Żadne żądania nie są wysyłane. Nigdy nie zmieniamy statusu punktu końcowego disabled; decyzja o przełączeniu go z powrotem na active zawsze należy do Ciebie.
failing — ustawiany automatycznie, gdy dostarczenie do punktu końcowego wyczerpie cały harmonogram ponawiania (8 prób w ciągu 24 godzin), ani razu nie otrzymując odpowiedzi 2xx. Punkt końcowy w stanie awarii nie otrzymuje dalszego ruchu. Po naprawieniu punktu końcowego ustaw jego status z powrotem na active za pomocą PATCH; dostarczenia, których harmonogram ponawiania jeszcze się nie wyczerpał, zostaną wznowione od miejsca, w którym się zatrzymały.

Wyświetl listę punktów końcowych

curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Zwraca tablicę obiektów punktu końcowego.

Utwórz punkt końcowy

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"]
  }'

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` dozwolony tylko dla `localhost` / `127.0.0.1`)
`events`	array	nie	Pusta lub pominięta wartość subskrybuje wszystkie zdarzenia. Należy użyć wartości wymienionych w sekcji Prawidłowe typy zdarzeń; duplikaty są usuwane

Zwraca 201 Created z obiektem punktu końcowego oraz dodatkowym polem najwyższego poziomu secret, zawierającym nieprzetworzony klucz podpisywania — 48-znakowy ciąg szesnastkowy:

{
  "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 zwracany wyłącznie podczas tworzenia. Kolejne odpowiedzi GET zawierają tylko secret_hint. Skopiuj pełną wartość do menedżera sekretów przed odrzuceniem odpowiedzi.

Zaktualizuj punkt końcowy

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`

Zwraca 200 OK ze zaktualizowanym obiektem punktu końcowego.

Wyślij dostarczenie testowe

Wyślij syntetyczne zdarzenie webhook.test do jednego punktu końcowego przy użyciu standardowego potoku dostarczania, w tym kanonicznej serializacji JSON, X-ThunderPhone-Signature, rejestrowania dostarczenia i obsługi ponowień. Test jest kierowany do wybranego punktu końcowego niezależnie od jego filtra events.

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 kopertę podobną do tej:

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

{
  "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, dostarczenie odbywa się według tego samego harmonogramu ponowień co standardowe dostarczenia zdarzeń.

Usuń endpoint

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 do adresu URL zostaje natychmiast zatrzymane; ponowne próby w toku są porzucane.

Powiązane

Katalog zdarzeń

Pełna lista wartości events, które możesz subskrybować.

Omówienie webhooków

Weryfikacja podpisu i semantyka dostarczania.

Webhooks

Function Tools

Punkty końcowe webhooków

Punkty końcowe

Obiekt punktu końcowego

Prawidłowe typy zdarzeń

Statusy punktów końcowych

Wyświetl listę punktów końcowych

Utwórz punkt końcowy

Pola żądania

Zaktualizuj punkt końcowy

Wyślij dostarczenie testowe

Usuń endpoint

Powiązane

Katalog zdarzeń

Omówienie webhooków

​Punkty końcowe

​Obiekt punktu końcowego

​Prawidłowe typy zdarzeń

​Statusy punktów końcowych

​Wyświetl listę punktów końcowych

​Utwórz punkt końcowy

​Pola żądania

​Zaktualizuj punkt końcowy

​Wyślij dostarczenie testowe

​Usuń endpoint

​Powiązane

Katalog zdarzeń

Omówienie webhooków

Punkty końcowe

Obiekt punktu końcowego

Prawidłowe typy zdarzeń

Statusy punktów końcowych

Wyświetl listę punktów końcowych

Utwórz punkt końcowy

Pola żądania

Zaktualizuj punkt końcowy

Wyślij dostarczenie testowe

Usuń endpoint

Powiązane