POST al tuo server quando accadono eventi
durante una chiamata: inizia una chiamata in entrata, termina una chiamata, si completa
un’esecuzione di valutazione, si attiva un avviso e così via. Esistono due modelli
di consegna:
Endpoint webhook (consigliati)
URL multipli, secret per endpoint, filtri degli eventi per endpoint
e nuovi tentativi automatici.
Gestisci tramite
GET/POST/PATCH/DELETE /v1/developer/webhook-endpoints.Webhook legacy a URL singolo
Un URL per organizzazione. Trasporta gli eventi del ciclo di vita della chiamata, inclusi gli
scambi di configurazione bloccanti. Gestito tramite
GET/PUT /v1/webhook.telephony.incoming, telephony.complete, telephony.tool,
web.incoming, web.complete, web.tool) vengono anche inviati al
webhook legacy a URL singolo: se disponi sia di un URL legacy sia di un endpoint
corrispondente, ricevi l’evento su entrambi i percorsi. Il comportamento bloccante
(lo scambio di configurazione telephony.incoming / web.incoming
e l’inoltro degli strumenti in modalità webhook)
è disponibile esclusivamente sul percorso legacy; ogni consegna agli endpoint è una
notifica fire-and-forget.
Formato del payload
Le consegne agli endpoint sono un oggetto JSON condata, event_id e
type:
event_id è univoco per ogni evento emesso. È identico tra i nuovi tentativi
e tra tutti gli endpoint che ricevono l’evento: usalo per la deduplicazione.
Il webhook legacy a URL singolo invia gli stessi type e data, ma
senza event_id:
Verifica della firma
Ogni richiesta include una firma HMAC-SHA256 sul corpo della richiesta non elaborato nell’headerX-ThunderPhone-Signature. La chiave di firma è il
secret dell’endpoint (oppure il secret webhook a livello di organizzazione per le
consegne legacy).
Passaggi
- Leggi il corpo della richiesta non elaborato prima di qualsiasi analisi.
- Calcola
hmac_sha256(secret, body).hexdigest(). - Confrontalo in tempo costante con l’header
X-ThunderPhone-Signature.
Semantica di consegna
Questa semantica si applica alle consegne agli endpoint. Il webhook legacy a URL singolo effettua un unico tentativo sincrono senza nuovi tentativi.Nuovi tentativi
Nuovi tentativi
Ogni evento viene tentato una volta immediatamente. Qualsiasi risposta
2xx
conferma la consegna. Per qualsiasi altro esito (non-2xx,
errore di connessione, timeout) riproviamo dopo 1 min, 5 min, 30 min, 2 h, 6 h,
12 h e 24 h dal primo tentativo — 8 tentativi nell’arco di
24 ore. Se ogni tentativo fallisce, la consegna si interrompe e l’endpoint
viene contrassegnato con status="failing" negli
endpoint webhook. Restituisci 2xx non appena
il payload viene accettato in modo durevole; elaboralo in modo asincrono.Ordinamento
Ordinamento
L’ordinamento delle consegne avviene secondo il principio del massimo impegno. In pratica consegniamo gli eventi nell’
ordine in cui vengono emessi, ma i nuovi tentativi possono riordinarli in caso di errore.
Esegui sempre deduplicazione e riconciliazione tramite
call_id / id oggetto.Duplicati
Duplicati
La consegna è almeno una volta: un nuovo tentativo dopo una risposta che non abbiamo
ricevuto può duplicare un evento. Ogni nuovo tentativo contiene lo stesso
event_id, quindi archivia gli id elaborati e ignora le ripetizioni. event_id è
condiviso anche tra gli endpoint — due endpoint iscritti allo
stesso evento ricevono lo stesso event_id.Timeout
Timeout
Le consegne agli endpoint hanno un timeout di 30 s per tentativo. Nel
percorso legacy, le richieste bloccanti che regolano il comportamento delle chiamate in tempo reale — lo
scambio di configurazione
telephony.incoming / web.incoming —
scadono dopo 10 s, ma una risposta lenta ritarda la presa in carico della chiamata,
quindi cerca di rispondere entro pochi secondi. L’invio di strumenti in modalità webhook tool dispatch consente 20 s.IP di origine
IP di origine
I webhook in uscita provengono dall’intervallo di IP cloud di ThunderPhone.
Se il firewall richiede un elenco di autorizzazione, contatta il supporto e condivideremo
gli intervalli attuali.
Scegliere tra webhook legacy e basati su endpoint
Le nuove integrazioni dovrebbero consumare gli eventi tramite webhook
basati su endpoint. Mantieni (o aggiungi) un URL legacy solo se configuri le chiamate
dinamicamente al momento della presa in carico o usi l’invio di strumenti in modalità webhook — questi
scambi richiesta/risposta vengono eseguiti solo nel percorso legacy.
Correlati
Catalogo degli eventi
Tutti i tipi di evento e i relativi payload.
Endpoint webhook
Gestisci più endpoint, filtri eventi e segreti.
telephony.incoming / web.incoming
La richiesta bloccante a cui il tuo server deve rispondere per configurare le chiamate.
telephony.complete / web.complete
Payload post-chiamata con trascrizione, registrazione e metriche.