Webhooks

Les webhooks permettent à SIP Caller de notifier vos systèmes en temps réel lorsqu’un événement se produit dans votre compte, par exemple lorsqu’une campagne est activée ou qu’un appel se termine. Au lieu d’interroger régulièrement l’API REST pour détecter les changements, votre application expose un point de terminaison HTTPS, et SIP Caller lui envoie une requête HTTP POST avec une charge utile JSON chaque fois qu’un événement auquel vous êtes abonné se produit.

Pour commencer à recevoir des webhooks, créez un webhook dans la Console Web, sélectionnez les événements qui vous intéressent, et assignez-le à vos campagnes. Consultez Webhooks pour un guide pas à pas.

Charge utile des événements

Chaque requête de webhook a un corps JSON avec la même enveloppe, où le champ data contient les détails de l’événement :

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

Champ	Description
id	Identifiant unique de l’événement. Si le même événement est livré plus d’une fois (par exemple, après une nouvelle tentative), il conserve le même id : vous pouvez donc l’utiliser pour écarter les doublons.
object	Toujours event.
apiVersion	Version du format de la charge utile, telle que configurée dans le webhook.
createdAt	Date et heure auxquelles l’événement s’est produit.
type	Type de l’événement, par exemple CampaignActivated ou CallEnded.
data	Détails de l’événement. Son contenu dépend du type d’événement, comme décrit sur la page de chaque événement.

Versions

Chaque webhook est configuré avec une version de charge utile. Lorsque SIP Caller apporte aux charges utiles des modifications non rétrocompatibles, il les publie dans une nouvelle version, afin que les intégrations existantes continuent de recevoir le format qu’elles attendent. Nous recommandons d’utiliser la dernière version pour les nouvelles intégrations. La page de chaque événement inclut un sélecteur de version qui affiche la charge utile de chaque version.

Types d’événements

Événement	Type	Envoyé lorsque
Campagne Activée	CampaignActivated	Une campagne est activée.
Campagne Mise en Pause	CampaignPaused	Une campagne active est mise en pause.
Campagne Reprise	CampaignResumed	Une campagne en pause est reprise.
Campagne Annulée	CampaignCanceled	Une campagne est annulée.
Campagne Terminée	CampaignFinished	Une campagne se termine.
Appel Terminé	CallEnded	Un appel effectué par une campagne se termine.

Vérifier les signatures

Chaque requête de webhook inclut un en-tête Sip-Caller-Signature, qui vous permet de vérifier que la requête a bien été envoyée par SIP Caller et n’a pas été modifiée :

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

La valeur t est l’horodatage de la signature de l’événement, et la valeur v1 est la signature. Pour la vérifier :

1. Concaténez l’horodatage (sous forme de chaîne), un point (.), et le corps JSON brut de la requête, exactement tel qu’il a été reçu.
2. Calculez un HMAC avec la fonction de hachage SHA-256, en utilisant le secret de signature du webhook comme clé et la chaîne concaténée comme message.
3. Comparez le résultat, en hexadécimal, avec la valeur v1. Ne traitez l’événement que si les deux valeurs correspondent.

Par exemple, en 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"])

Des exemples complets sont disponibles pour Python et .NET. Le secret de signature peut être régénéré depuis la Console Web ; dans ce cas, mettez immédiatement à jour votre application, car les signatures générées avec le nouveau secret ne seront pas validées avec l’ancien.

Répondre rapidement

Votre point de terminaison doit répondre avec un code de statut 2xx dès qu’il reçoit l’événement, et effectuer tout traitement long ensuite (par exemple, dans une tâche en arrière-plan). Si votre point de terminaison ne répond pas à temps, ou répond avec une erreur, SIP Caller relance la livraison selon les paramètres de délai d’expiration et de nouvelles tentatives du webhook. Comme un événement peut être livré plus d’une fois, rendez votre traitement idempotent en utilisant l’id de l’événement.