Définition
Un webhook est une requête HTTP qu'un système envoie à une URL d'un autre système quand quelque chose se produit ou est nécessaire. Dans un agent vocal, un outil webhook est la façon dont l'agent appelle votre propre point de terminaison pendant un appel.
Comment fonctionne un webhook
La plupart des API attendent qu’on les interroge. Un webhook inverse cela : le système émetteur fait une requête HTTP à une adresse que vous lui avez donnée. Le récepteur expose une URL, l’émetteur l’appelle avec une méthode comme POST, un ensemble d’en-têtes et un corps, et le récepteur répond par un code d’état.
Les webhooks apparaissent de deux façons dans les plateformes vocales.
- Rappels d’événements. La plateforme notifie votre serveur de quelque chose qui s’est produit, comme la fin d’un appel, pour que vous puissiez stocker une transcription ou mettre à jour une fiche.
- Outils webhook. L’agent appelle votre point de terminaison au milieu d’un appel, pour consulter quelque chose ou faire quelque chose, et exploite la réponse. C’est une forme d’appel d’outils.
Dans les Managed Agents de Cartesia, un outil webhook est défini par une URL, une méthode HTTP, des paramètres, des en-têtes et une authentification. Cartesia documente ces comportements :
- L’URL doit être en HTTPS.
- Le modèle décide quand l’appeler d’après la description de l’outil.
- Chaque paramètre est renseigné par le modèle, par une valeur fixe ou par une variable dynamique.
- Le délai d’expiration de la requête est de 20 secondes par défaut.
- Un délai dépassé, un point de terminaison injoignable ou un statut non 2xx renvoie un résultat d’erreur au modèle, et l’appel continue.
Pourquoi c’est important pour les agents vocaux
Un webhook est la liaison entre la conversation et vos systèmes : son comportement s’entend donc. Un point de terminaison lent crée du silence. Un point de terminaison qui échoue renvoie une erreur dont le modèle doit parler : le corps de la réponse doit donc dire ce qui n’a pas marché avec des mots que l’agent peut utiliser.
Concevez le côté récepteur comme si l’appelant regardait. Renvoyez un texte court et simple, car un long export JSON coûte du temps de lecture au modèle. Rendez les opérations qui modifient des données sûres à répéter, car une nouvelle tentative ou une requête dupliquée du modèle ne doit pas réserver deux rendez-vous. Authentifiez la requête et vérifiez chaque paramètre sur votre serveur, car les valeurs fournies par le modèle viennent d’une conversation avec un inconnu.
Réglez le délai d’expiration d’après la pause qu’acceptera l’appelant. Un délai de 20 secondes est long à rester silencieux pendant un appel : associez donc les outils lents à une phrase prononcée avant leur exécution.
Exemple
Un outil webhook illustratif pour une ligne de commandes :
- Méthode et URL : GET
https://api.example.com/orders/{order_id} - Description : « Consulte l’état d’une commande à partir de son numéro. »
- Réponse : « Expédiée mardi, arrive vendredi. »
Le modèle renseigne order_id d’après ce qu’a dit l’appelant et prononce la réponse avec ses propres mots.