Webhooks

Punkty końcowe webhooków

Zarządzaj wieloma adresami URL webhooków z sekretami i filtrami zdarzeń dla każdego punktu końcowego.

System webhooków oparty na punktach końcowych pozwala zarejestrować wiele miejsc docelowych na organizację, każde z własnym sekretem, własnym statusem 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 utrzymywany dla zachowania zgodności wstecznej, ale obsługuje tylko jeden adres URL na organizację.

Punkty końcowe#

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

Prawidłowe typy zdarzeń#

Wartość events jest sprawdzana względem tego dokładnego 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
• 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; przywrócenie go do active zawsze zależy od Ciebie.
• failing — ustawiany automatycznie, gdy dostarczenie do punktu końcowego wykorzysta cały harmonogram ponowień (8 prób w ciągu 24 godzin), nie otrzymując ani jednej odpowiedzi 2xx. Punkt końcowy w stanie błędu nie otrzymuje dalszego ruchu. Po naprawieniu punktu końcowego ustaw przez PATCH jego status z powrotem na active; dostarczenia, których harmonogram ponowień jeszcze nie wygasł, zostaną wznowione od miejsca, w którym zostały 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 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#

Zwraca 201 Created z obiektem punktu końcowego oraz dodatkowym polem secret na najwyższym poziomie zawierającym nieprzetworzony klucz podpisujący — 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.

Wyślij dostawę testową#

Wyślij syntetyczne zdarzenie webhook.test do jednego punktu końcowego za pomocą standardowego potoku dostarczania, w tym kanonicznej serializacji JSON, X-ThunderPhone-Signature, rejestrowania dostawy i śledzenia 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 zwraca błąd. Sprawdź success, status, response_code i error, aby poznać wynik dostawy:

{
  "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, dostawa jest realizowana zgodnie z tym samym harmonogramem ponowień co zwykłe dostawy zdarzeń.

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 adres URL zostaje natychmiast zatrzymane; ponowienia w toku są przerywane.

Powiązane#