Webhook

SIP Caller può attivare webhook per notificare a sistemi esterni gli eventi che accadono sulla nostra piattaforma. In questo modo, è possibile sviluppare molte integrazioni personalizzate utili tra SIP Caller e altri sistemi. I webhook richiedono il piano Enterprise.
La procedura prevede 2 passaggi:

1. Creare un webhook.
2. Configurare una campagna con un webhook esistente.

Crea un webhook

Per creare un webhook, accedi a SIP Caller e vai su Impostazioni > Webhook. Poi fai clic sul pulsante "Crea" per aprire la finestra di dialogo di creazione del Webhook e procedi come segue:

• Inserisci un nome descrittivo per il webhook, così potrai selezionarlo facilmente in seguito.
• Inserisci l'URL che vuoi che SIP Caller invochi quando si verificano gli eventi.
• Seleziona la versione. Ti consigliamo di utilizzare l'ultima versione per sfruttare le funzionalità più recenti, ma puoi anche configurare una versione precedente per motivi di retrocompatibilità.
• Seleziona gli eventi a cui sei interessato. Gli eventi disponibili sono descritti in Tipi di evento.
• Configura le impostazioni avanzate secondo le tue esigenze. Quando crei un webhook, hanno i seguenti valori predefiniti:
  • Timeout in Secondi: 30. Il tempo che SIP Caller attende la risposta del tuo endpoint.
  • Numero Massimo di Tentativi: 5. Il numero massimo di volte in cui SIP Caller prova a consegnare ogni evento.
  • Età Massima dell'Evento in Ore: 24. Gli eventi in attesa di essere inviati da più tempo, ad esempio mentre il webhook è disabilitato, vengono scartati.
  • Numero Massimo di Connessioni Simultanee: 8. Il numero massimo di richieste che SIP Caller invia contemporaneamente al tuo endpoint.

Tipi di evento

Un webhook può notificare i seguenti eventi:

• Campagna Attivata: una campagna viene attivata, da un utente dalla console di SIP Caller o da un'applicazione tramite la REST API.
• Campagna Messa in Pausa: una campagna attiva viene messa in pausa.
• Campagna Ripresa: una campagna in pausa viene attivata di nuovo.
• Campagna Annullata: una campagna viene annullata.
• Campagna Terminata: una campagna termina.
• Chiamata Terminata: una chiamata effettuata da una campagna termina, qualunque sia il suo risultato.

Gli eventi delle campagne contengono la configurazione della campagna e, quando la modifica è stata effettuata da un utente o da un'applicazione, l'origine della modifica. L'evento Chiamata Terminata contiene i dettagli della chiamata: il numero chiamato e i valori delle sue variabili, i risultati dello squillo e della risposta, le durate, i risultati delle interazioni con il contatto (come gli input DTMF o gli obiettivi dell'agente IA), i dettagli del trasferimento, e l'esito finale della chiamata, incluso quando verrà effettuato un nuovo tentativo. Questo è l'evento da utilizzare per aggiornare i tuoi sistemi, come un CRM, con il risultato di ogni chiamata.

Consegna e nuovi tentativi

Ogni evento viene inviato come richiesta HTTP POST all'URL del webhook, con un payload JSON e l'intestazione "Sip-Caller-Signature", in modo che il tuo endpoint possa convalidare che la richiesta sia stata inviata da SIP Caller.

La consegna ha esito positivo quando il tuo endpoint risponde con un codice di stato HTTP 2xx entro il timeout configurato. Quando l'endpoint risponde con qualsiasi altro codice di stato, non risponde in tempo, o non è raggiungibile, la consegna fallisce, e SIP Caller la ritenta automaticamente: il primo nuovo tentativo viene effettuato 5 minuti dopo il tentativo fallito, il secondo 1 ora dopo, il terzo 4 ore dopo, e ogni nuovo tentativo successivo attende 4 ore in più rispetto al precedente, fino al raggiungimento del numero massimo di tentativi. Dopo l'ultimo tentativo, l'evento viene contrassegnato come fallito.

Ogni tentativo di consegna viene registrato, insieme al suo risultato, al codice di risposta e al tempo di risposta, così puoi verificare lo stato di ogni evento come descritto in Risoluzione dei problemi dei webhook.

Configura una campagna per attivare i webhook

Una volta creato il webhook, devi configurare le campagne che lo utilizzeranno. Per fare questo, seleziona semplicemente il webhook dalla scheda Integrazione.

Abilita e disabilita i webhook

Se riscontri un problema durante l'elaborazione dei webhook attivati da SIP Caller, puoi mettere in pausa la generazione di questi eventi. Quando lo fai, SIP Caller metterà in coda questi eventi durante il tempo che hai configurato al momento della creazione, dandoti il tempo di correggere il tuo algoritmo di elaborazione degli eventi, in modo da poter poi riabilitare i webhook. Per fare questo, vai su Impostazioni > Webhook, e seleziona i pulsanti "Abilita" o "Disabilita" nella colonna Azioni.

Rigenera il segreto di firma

Dalla colonna Azioni nell'elenco dei webhook, puoi anche fare clic sul pulsante per rigenerare il segreto di firma. Questo farà sì che SIP Caller inizi a firmare i webhook utilizzando il nuovo segreto. Qualsiasi integrazione che utilizzi il vecchio segreto smetterà di funzionare, poiché la convalida fallirà, quindi devi prestare attenzione quando esegui questa azione.

Convalida la firma del webhook

Ogni notifica webhook inviata da SIP Caller avrà l'intestazione "Sip-Caller-Signature" nella richiesta HTTP, impostata su un valore simile al seguente:

t=1728776932,v1=df9da282f3ffe9a7d855cc11589d86d33852ee0bbc1abaacab854c7f52e6efae

Il valore assegnato a "t" è un timestamp che indica quando è stato generato l'evento. Il valore assegnato a "v1" è la firma del webhook. Avrai bisogno di entrambi i valori per eseguire la verifica, come segue:

1. Concatena il timestamp (come stringa), un punto (.), e il payload JSON ricevuto nel corpo della richiesta HTTP. Ad esempio:

   1728776932.{"id" : "01928322-860c-77f9-9c3b-7f8abe3b6afd".......}

2. Calcola la firma del webhook attesa, calcolando un HMAC utilizzando la funzione hash SHA256. Usa il segreto di firma del webhook come chiave, e il valore risultante dalla concatenazione nel passaggio precedente come messaggio.
3. Confronta la firma del webhook calcolata con il valore preso da "v1" nell'intestazione della richiesta. Se entrambi i valori corrispondono, allora puoi procedere in sicurezza con l'elaborazione dell'evento webhook.

Abbiamo creato esempi di codice che mostrano come eseguire questa convalida in un'applicazione Python o .NET.

Risoluzione dei problemi dei webhook

Dalla console di SIP Caller > Impostazioni > Webhook, puoi fare clic su un webhook e verificare tutti gli eventi che sono stati notificati.
L'elenco può essere filtrato per identificare l'evento che stai cercando. Poi, quando si fa clic su un evento, verrà mostrato un pannello sul lato destro, con i dettagli di ciascun tentativo di notifica.

Riferimento dati dei webhook

I webhook generati da SIP Caller sono richieste HTTP POST, contenenti JSON come payload, e ogni richiesta include una versione che ci permette di far evolvere il formato del payload nel tempo senza interrompere le integrazioni esistenti. Il riferimento JSON completo per ogni tipo di evento e versione è disponibile nella pagina Riferimento dati dei webhook.