Skip to main content
ThunderPhone wysyła żądania HTTP POST do Twojego serwera, gdy podczas połączenia coś się wydarzy — rozpocznie się połączenie przychodzące, połączenie się zakończy, zakończy się uruchomienie oceny, zostanie wyzwolony alert itd. Dostępne są dwa modele dostarczania:

Endpointy webhooków (zalecane)

Wiele adresów URL, sekrety dla poszczególnych endpointów, filtry zdarzeń dla poszczególnych endpointów oraz automatyczne ponawianie prób. Zarządzaj przez GET/POST/PATCH/DELETE /v1/developer/webhook-endpoints.

Starszy webhook z pojedynczym adresem URL

Jeden adres URL na organizację. Obejmuje zdarzenia cyklu życia połączenia, w tym blokujące wymiany konfiguracji. Zarządzany przez GET/PUT /v1/webhook.
Wszystkie dziesięć typów zdarzeń z katalogu zdarzeń jest dostarczanych przez endpointy webhooków. Sześć zdarzeń cyklu życia połączenia (telephony.incoming, telephony.complete, telephony.tool, web.incoming, web.complete, web.tool) jest również wysyłanych do starszego webhooka z pojedynczym adresem URL — jeśli masz zarówno starszy adres URL, jak i pasujący endpoint, otrzymasz zdarzenie na obu ścieżkach. Zachowanie blokujące (wymiana konfiguracji telephony.incoming / web.incoming oraz wywoływanie narzędzi w trybie webhooka) występuje wyłącznie na starszej ścieżce; każde dostarczenie do endpointu jest powiadomieniem typu fire-and-forget.

Format ładunku

Dostarczenia do endpointów mają postać obiektu JSON z polami data, event_id i type:
event_id jest unikalny dla każdego wyemitowanego zdarzenia. Jest identyczny przy ponownych próbach oraz we wszystkich endpointach, które otrzymują zdarzenie — używaj go do deduplikacji. Starszy webhook z pojedynczym adresem URL wysyła te same pola type i data, ale bez event_id:
W transmisji każde ciało jest serializowane kanonicznie — klucze są sortowane alfabetycznie, bez białych znaków, w UTF-8. Przykłady z formatowaniem w tej dokumentacji służą wyłącznie czytelności. Pełną listę typów zdarzeń i pól ładunku znajdziesz w katalogu zdarzeń.

Weryfikacja podpisu

Każde żądanie zawiera podpis HMAC-SHA256 obejmujący surową treść żądania w nagłówku X-ThunderPhone-Signature. Kluczem podpisującym jest secret punktu końcowego (lub secret webhooka na poziomie organizacji w przypadku starszych dostaw).

Kroki

  1. Odczytaj surową treść żądania przed jakimkolwiek parsowaniem.
  2. Oblicz hmac_sha256(secret, body).hexdigest().
  3. Porównaj w czasie stałym z nagłówkiem X-ThunderPhone-Signature.
Podpisujemy dokładnie bajty, które przesyłamy, a są one kanoniczną serializacją JSON (posortowane klucze, kompaktowe separatory). Dlatego weryfikacja względem surowej treści zawsze działa — a jeśli framework udostępnia tylko sparsowany JSON, ponowna serializacja z posortowanymi kluczami i kompaktowymi separatorami daje identyczne bajty. Oba podejścia opisano w przewodniku po weryfikacji.

Semantyka dostarczania

Ta semantyka dotyczy dostarczania do punktów końcowych. Starszy webhook z pojedynczym adresem URL wykonuje jedną synchroniczną próbę bez ponowień.
Każde zdarzenie jest natychmiast podejmowane raz. Każda odpowiedź 2xx potwierdza dostarczenie. W przypadku każdego innego wyniku (innego niż 2xx, błędu połączenia, przekroczenia czasu) ponawiamy próbę po 1 min, 5 min, 30 min, 2 godz., 6 godz., 12 godz. i 24 godz. od pierwszej próby — łącznie 8 prób w ciągu 24 godzin. Jeśli wszystkie próby się nie powiodą, dostarczanie zostaje zatrzymane, a punkt końcowy otrzymuje oznaczenie status="failing" w punktach końcowych webhooków. Zwróć 2xx, gdy tylko ładunek zostanie trwale zaakceptowany; przetwarzaj go asynchronicznie.
Kolejność dostarczania jest zapewniana w miarę możliwości. W praktyce dostarczamy zdarzenia w kolejności ich emisji, ale ponowienia mogą zmienić kolejność po niepowodzeniu. Zawsze usuwaj duplikaty i uzgadniaj dane według call_id / identyfikatora obiektu.
Dostarczanie jest co najmniej jednokrotne: ponowienie po odpowiedzi, której nie otrzymaliśmy, może zduplikować zdarzenie. Każde ponowienie zawiera ten sam event_id, dlatego przechowuj identyfikatory przetworzonych zdarzeń i pomijaj powtórzenia. event_id jest również współdzielony między punktami końcowymi — dwa punkty końcowe subskrybujące to samo zdarzenie otrzymują ten sam event_id.
Dostarczanie do punktów końcowych ma limit czasu 30 s na próbę. W starszej ścieżce blokujące żądania sterujące zachowaniem aktywnego połączenia — wymiana konfiguracji telephony.incoming / web.incoming — przekraczają limit czasu po 10 s, ale wolna odpowiedź opóźnia odebranie połączenia, dlatego staraj się odpowiedzieć w ciągu kilku sekund. Dyspozycja narzędzi w trybie webhooków tool dispatch pozwala na 20 s.
Wychodzące webhooki pochodzą z zakresu adresów IP chmury ThunderPhone. Jeśli zapora sieciowa wymaga listy dozwolonych adresów, skontaktuj się z pomocą techniczną, a udostępnimy aktualne zakresy.

Wybór między starszymi webhookami a webhookami opartymi na punktach końcowych

Nowe integracje powinny odbierać zdarzenia przez webhooki oparte na punktach końcowych. Zachowaj (lub dodaj) starszy adres URL tylko wtedy, gdy konfigurujesz połączenia dynamicznie w momencie odbierania albo używasz dyspozycji narzędzi w trybie webhooków — te wymiany żądań i odpowiedzi działają wyłącznie w starszej ścieżce.

Powiązane

Katalog zdarzeń

Wszystkie typy zdarzeń i ich ładunki.

Punkty końcowe webhooków

Zarządzaj wieloma punktami końcowymi, filtrami zdarzeń i sekretami.

telephony.incoming / web.incoming

Blokujące żądanie, na które serwer musi odpowiedzieć, aby skonfigurować połączenia.

telephony.complete / web.complete

Ładunek po połączeniu z transkrypcją, nagraniem i metrykami.