Vue d’ensemble

SIP Caller peut déclencher des webhooks afin de notifier des systèmes externes des événements qui se produisent sur notre plateforme. Ainsi, de nombreuses intégrations personnalisées utiles peuvent être développées entre SIP Caller et d’autres systèmes.
La procédure comporte 2 étapes :

1. Créer un webhook.
2. Configurer une campagne avec un webhook existant.

Créer un webhook

Pour créer un webhook, connectez-vous à SIP Caller et allez dans Réglages > Webhooks. Cliquez ensuite sur le bouton « Créer » pour ouvrir la boîte de dialogue de création de webhook et procédez comme suit :

• Saisissez un nom convivial pour le webhook, afin de pouvoir le sélectionner facilement plus tard.
• Saisissez l’URL que vous souhaitez que SIP Caller invoque lorsque les événements se produisent.
• Sélectionnez la version. Nous vous recommandons d’utiliser la dernière version pour profiter des fonctionnalités les plus récentes, mais vous pouvez également configurer une version antérieure pour des raisons de rétrocompatibilité.
• Sélectionnez les événements qui vous intéressent.
• Configurez le délai d’expiration, le nombre maximal de tentatives, l’âge maximal des événements et le nombre maximal de connexions simultanées, selon vos besoins.

Configurer une campagne pour déclencher des webhooks

Une fois le webhook créé, vous devez configurer les campagnes pour l’utiliser. Pour ce faire, sélectionnez simplement le webhook depuis l’onglet Intégration.

Activer et désactiver les webhooks

Si vous rencontrez un problème lors du traitement des webhooks déclenchés par SIP Caller, vous pouvez mettre en pause la génération de ces événements. Lorsque vous faites cela, SIP Caller mettra ces événements en file d’attente pendant la durée que vous avez configurée lors de sa création, vous donnant le temps de corriger votre algorithme de traitement d’événements, afin de pouvoir ensuite réactiver les webhooks. Pour ce faire, allez dans Réglages > Webhooks, et sélectionnez les boutons « Activer » ou « Désactiver » dans la colonne Actions.

Régénérer le secret de signature

Depuis la colonne Actions dans la liste des webhooks, vous pouvez également cliquer sur le bouton pour régénérer le secret de signature. Ceci amènera SIP Caller à commencer à signer les webhooks à l’aide du nouveau secret. Toute intégration que vous avez utilisant l’ancien secret cessera de fonctionner, car la validation échouera ; vous devez donc être prudent lors de l’exécution de cette action.

Valider la signature du webhook

Chaque notification webhook envoyée par SIP Caller comportera l’en-tête « Sip-Caller-Signature » dans la requête HTTP, défini sur une valeur similaire à la suivante :

t=1728776932,v1=df9da282f3ffe9a7d855cc11589d86d33852ee0bbc1abaacab854c7f52e6efae

La valeur assignée à « t » est un horodatage indiquant quand l’événement a été généré. La valeur assignée à « v1 » est la signature du webhook. Vous aurez besoin des deux valeurs pour effectuer la vérification, comme suit :

1. Concaténez l’horodatage (en tant que chaîne de caractères), un point (.), et la charge utile JSON reçue dans le corps de la requête HTTP. Par exemple :

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

2. Calculez la signature de webhook attendue, en calculant un HMAC à l’aide de la fonction de hachage SHA256. Utilisez le secret de signature du webhook comme clé, et la valeur résultant de la concaténation de l’étape précédente comme message.
3. Comparez la signature de webhook calculée avec la valeur extraite de « v1 » dans l’en-tête de la requête. Si les deux valeurs correspondent, vous pouvez alors procéder en toute sécurité au traitement de l’événement webhook.

Nous avons créé des exemples de code montrant comment effectuer cette validation dans une application Python ou .NET.

Dépannage des webhooks

Depuis la console SIP Caller > Réglages > Webhooks, vous pouvez cliquer sur un webhook et consulter tous les événements qui ont été notifiés.
La liste peut être filtrée afin d’identifier l’événement que vous recherchez. Ensuite, lorsqu’un événement est cliqué, un panneau sera affiché sur le côté droit, avec les détails de chaque tentative de notification.

Référence des données de webhooks

Les webhooks générés par SIP Caller sont des requêtes HTTP POST, contenant du JSON comme charge utile, et chaque requête est associée à une version afin que nous puissions faire évoluer le format de la charge utile au fil du temps sans casser les intégrations existantes. La référence JSON complète pour chaque type d'événement et chaque version est disponible sur la page Référence des données de webhooks.