Skip to main content
ThunderPhone invia richieste HTTP 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.
Tutti e dieci i tipi di evento nel catalogo degli eventi vengono consegnati tramite endpoint webhook. I sei eventi del ciclo di vita della chiamata (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 con data, 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:
Sulla rete, ogni corpo viene serializzato in modo canonico: chiavi ordinate alfabeticamente, nessuno spazio bianco, UTF-8. Gli esempi formattati in modo leggibile in questa documentazione sono solo a scopo di leggibilità. Consulta il Catalogo degli eventi per l’elenco completo dei tipi di evento e dei campi del payload.

Verifica della firma

Ogni richiesta include una firma HMAC-SHA256 sul corpo della richiesta non elaborato nell’header X-ThunderPhone-Signature. La chiave di firma è il secret dell’endpoint (oppure il secret webhook a livello di organizzazione per le consegne legacy).

Passaggi

  1. Leggi il corpo della richiesta non elaborato prima di qualsiasi analisi.
  2. Calcola hmac_sha256(secret, body).hexdigest().
  3. Confrontalo in tempo costante con l’header X-ThunderPhone-Signature.
Firmiamo esattamente i byte che trasmettiamo e tali byte corrispondono alla serializzazione JSON canonica (chiavi ordinate, separatori compatti). Pertanto, la verifica rispetto al corpo non elaborato funziona sempre — e se il tuo framework fornisce solo JSON analizzato, serializzarlo nuovamente con chiavi ordinate e separatori compatti produce byte identici. Entrambi gli approcci sono trattati nella guida alla verifica.

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