Webhook

I webhook permettono a SIP Caller di notificare ai tuoi sistemi in tempo reale quando succede qualcosa nel tuo account, ad esempio quando una campagna viene attivata o termina una chiamata. Invece di interrogare periodicamente la REST API per verificare la presenza di modifiche, la tua applicazione espone un endpoint HTTPS, e SIP Caller gli invia una richiesta HTTP POST con un payload JSON ogni volta che si verifica un evento a cui è iscritta.

Per iniziare a ricevere i webhook, crea un webhook nella Console Web, seleziona gli eventi a cui sei interessato e assegnalo alle tue campagne. Consulta Webhooks per una guida passo passo.

Payload dell'evento

Ogni richiesta webhook ha un corpo JSON con la stessa struttura, in cui il campo data contiene i dettagli dell'evento:

{
  "id": "01928321-9129-7f25-8ad3-80c57b16d3ed",
  "object": "event",
  "apiVersion": 2,
  "createdAt": "2024-10-12T23:47:48.133",
  "type": "CampaignActivated",
  "data": {
    ...
  }
}

Campo	Descrizione
id	Identificatore univoco dell'evento. Se lo stesso evento viene consegnato più di una volta (ad esempio, dopo un nuovo tentativo), mantiene lo stesso id, quindi puoi utilizzarlo per scartare i duplicati.
object	Sempre event.
apiVersion	Versione del formato del payload, così come configurata nel webhook.
createdAt	Data e ora in cui si è verificato l'evento.
type	Tipo dell'evento, ad esempio CampaignActivated o CallEnded.
data	Dettagli dell'evento. Il suo contenuto dipende dal tipo di evento, come descritto nella pagina di ciascun evento.

Versioni

Ogni webhook è configurato con una versione del payload. Quando SIP Caller introduce nei payload modifiche non retrocompatibili, le rilascia con una nuova versione, così le integrazioni esistenti continuano a ricevere il formato che si aspettano. Ti consigliamo di utilizzare l'ultima versione per le nuove integrazioni. La pagina di ciascun evento include un selettore di versione che mostra il payload di ogni versione.

Tipi di evento

Evento	Tipo	Inviato quando
Campagna Attivata	CampaignActivated	Una campagna viene attivata.
Campagna Messa in Pausa	CampaignPaused	Una campagna attiva viene messa in pausa.
Campagna Ripresa	CampaignResumed	Una campagna in pausa viene ripresa.
Campagna Annullata	CampaignCanceled	Una campagna viene annullata.
Campagna Terminata	CampaignFinished	Una campagna termina.
Chiamata Terminata	CallEnded	Termina una chiamata effettuata da una campagna.

Verificare le firme

Ogni richiesta webhook include un'intestazione Sip-Caller-Signature, che ti permette di verificare che la richiesta sia stata inviata da SIP Caller e non sia stata modificata:

Sip-Caller-Signature: t=1728776932,v1=df9da282f3ffe9a7d855cc11589d86d33852ee0bbc1abaacab854c7f52e6efae

Il valore t è il timestamp in cui l'evento è stato firmato, e il valore v1 è la firma. Per verificarla:

1. Concatena il timestamp (come stringa), un punto (.) e il corpo JSON grezzo della richiesta, esattamente come ricevuto.
2. Calcola un HMAC con la funzione hash SHA-256, utilizzando il segreto di firma del webhook come chiave e la stringa concatenata come messaggio.
3. Confronta il risultato, in esadecimale, con il valore v1. Elabora l'evento solo se entrambi i valori corrispondono.

Ad esempio, in Python:

import hashlib
import hmac

def is_valid_signature(header: str, body: bytes, secret: str) -> bool:
    parts = dict(item.split("=", 1) for item in header.split(","))
    message = parts["t"].encode() + b"." + body
    expected = hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

Sono disponibili esempi completi per Python e .NET. Il segreto di firma può essere rigenerato dalla Console Web; quando lo fai, aggiorna subito la tua applicazione, poiché le firme create con il nuovo segreto non verranno convalidate con quello vecchio.

Rispondere rapidamente

Il tuo endpoint deve rispondere con un codice di stato 2xx non appena riceve l'evento, ed eseguire in seguito qualsiasi elaborazione che richieda tempo (ad esempio, in un processo in background). Se il tuo endpoint non risponde in tempo, o risponde con un errore, SIP Caller ritenta la consegna in base alle impostazioni di timeout e di nuovi tentativi del webhook. Poiché un evento può essere consegnato più di una volta, rendi la tua elaborazione idempotente utilizzando l'id dell'evento.