Panoramica

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.
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 > Webhooks. 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.
• Configura il timeout, il numero massimo di tentativi, l'età massima dell'evento e il numero massimo di connessioni simultanee, secondo le tue esigenze.

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