Punkty końcowe webhooków

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, który zachowano dla zgodności wstecznej, ale obsługuje tylko jeden adres URL na organizację.

Endpointy#

Obiekt punktu końcowego#

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

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, 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#

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. 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#

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#

Zwraca 201 Created z obiektem punktu końcowego oraz dodatkowym polem secret najwyższego poziomu 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"
}

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

Zwraca 200 OK ze zaktualizowanym obiektem punktu końcowego.

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.

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

Zwraca 200 OK:

{
  "endpoint": { "id": "c4d5e6f7-...", "secret_hint": "7f3a…c21d", "...": "..." },
  "secret": "7f3a90b2c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5c21d",
  "rotated_endpoint_ids": ["c4d5e6f7-..."]
}

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.

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:

{
  "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, ThunderPhone ponowi ją raz po około minucie, a następnie zakończy; dostarczenie będzie wtedy mieć status: "failed" w sekcji Debugowanie dostarczeń. 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.

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ń. Pominięcie go zachowuje ogólne zachowanie webhook.test.

Usuń punkt końcowy#

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. 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#