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.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 polamidata, 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:
Weryfikacja podpisu
Każde żądanie zawiera podpis HMAC-SHA256 obejmujący surową treść żądania w nagłówkuX-ThunderPhone-Signature. Kluczem podpisującym jest
secret punktu końcowego (lub secret webhooka na poziomie organizacji w przypadku
starszych dostaw).
Kroki
- Odczytaj surową treść żądania przed jakimkolwiek parsowaniem.
- Oblicz
hmac_sha256(secret, body).hexdigest(). - Porównaj w czasie stałym z nagłówkiem
X-ThunderPhone-Signature.
Semantyka dostarczania
Ta semantyka dotyczy dostarczania do punktów końcowych. Starszy webhook z pojedynczym adresem URL wykonuje jedną synchroniczną próbę bez ponowień.Ponowienia
Ponowienia
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ść
Kolejność
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.Duplikaty
Duplikaty
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.Limity czasu
Limity czasu
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.Źródłowe adresy IP
Źródłowe adresy IP
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.