Webhooks

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. Les webhooks nécessitent le forfait Enterprise.
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 Paramètres > 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. Les événements disponibles sont décrits dans Types d’événements.
• Configurez les paramètres avancés selon vos besoins. Lorsque vous créez un webhook, ils ont les valeurs par défaut suivantes :
  • Délai d’attente : 30 secondes. Le temps pendant lequel SIP Caller attend la réponse de votre endpoint.
  • Nombre maximal de tentatives de nouvelle tentative : 5. Le nombre maximal de fois que SIP Caller tente de livrer chaque événement.
  • Âge maximum de l’événement : 24 heures. Les événements en attente d’envoi depuis plus longtemps, par exemple pendant que le webhook est désactivé, sont rejetés.
  • Nombre maximal de connexions simultanées : 8. Le nombre maximal de requêtes que SIP Caller envoie simultanément à votre endpoint.

Types d’événements

Un webhook peut notifier les événements suivants :

• Campagne activée : une campagne est activée, par un utilisateur depuis la console SIP Caller ou par une application via l’API REST.
• Campagne suspendue : une campagne active est mise en pause.
• Reprise de la campagne : une campagne en pause est de nouveau activée.
• Campagne annulée : une campagne est annulée.
• Campagne terminée : une campagne se termine.
• Appel terminé : un appel effectué par une campagne se termine, quel que soit son résultat.

Les événements de campagne contiennent la configuration de la campagne et, lorsque la modification a été effectuée par un utilisateur ou une application, l’origine de la modification. L’événement Appel terminé contient les détails de l’appel : le numéro appelé et les valeurs de ses variables, les résultats de sonnerie et de réponse, les durées, les résultats des interactions avec le contact (comme les entrées DTMF ou les objectifs de l’agent IA), les détails du transfert, et le résultat final de l’appel, y compris le moment où il sera relancé. C’est l’événement à utiliser pour mettre à jour vos propres systèmes, comme un CRM, avec le résultat de chaque appel.

Livraison et nouvelles tentatives

Chaque événement est envoyé sous la forme d’une requête HTTP POST vers l’URL du webhook, avec une charge utile JSON et l’en-tête « Sip-Caller-Signature », afin que votre endpoint puisse valider que la requête a bien été envoyée par SIP Caller.

La livraison réussit lorsque votre endpoint répond avec un code de statut HTTP 2xx dans le délai d’attente configuré. Lorsque l’endpoint répond avec un autre code de statut, ne répond pas à temps ou est injoignable, la livraison échoue, et SIP Caller la relance automatiquement : la première nouvelle tentative a lieu 5 minutes après la tentative échouée, la deuxième 1 heure après, la troisième 4 heures après, et chaque nouvelle tentative suivante attend 4 heures de plus que la précédente, jusqu’à atteindre le nombre maximal de tentatives. Après la dernière tentative, l’événement est marqué comme échoué.

Chaque tentative de livraison est enregistrée, avec son résultat, le code de réponse et le temps de réponse, afin que vous puissiez vérifier le statut de chaque événement comme décrit dans Dépannage des webhooks.

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 Paramètres > 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 > Paramètres > 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.