Documentation

Webhooks

Envoyez des événements signés en temps réel à des services externes.

Les webhooks envoient des notifications signées lorsqu’un prospect, un formulaire, une conversation ou une escalade change d’état. Ils nécessitent un forfait Hobby ou supérieur avec facturation active.

Configurer un point de terminaison

Ouvrez Paramètres → Webhooks sur un agent, choisissez un ou plusieurs événements, saisissez un point de terminaison HTTPS public, puis créez les abonnements. Agentkit conserve un seul secret de signature pour toutes les lignes d’événements d’un même point de terminaison. Les propriétaires du compte peuvent le révéler ou le faire pivoter depuis la carte du point de terminaison.

Les noms d’événements pris en charge sont :

  • lead_created
  • form_submission (alias historique de prospect)
  • custom_form_submitted
  • conversation_started
  • conversation_ended
  • escalation_created

conversation_ended est émis après 30 minutes sans message. Sa transcription est un instantané immuable d’au plus 200 messages, chaque message étant limité à 2 000 caractères. Les conversations qui ne se déroulent que dans le Playground, ainsi que celles sans message de l’utilisateur, ne sont pas envoyées. L’analyse de la transcription vaut actuellement null.

Enveloppe

Chaque événement utilise la même enveloppe stable :

{
  "event": "conversation_started",
  "eventId": "evt_91d0a3ce-5a9d-4b67-a454-bafb9484281a",
  "timestamp": "2026-07-14T13:05:02.000Z",
  "data": {
    "conversationId": "0b8e43d2-6cdf-42a8-8df1-a17f082df99f",
    "conversationReferenceId": "a1b2c3d4e5f6a7b8",
    "chatbotId": "d21c2aca-52d7-4056-a7d6-805713d3d39c",
    "source": "widget",
    "startedAt": "2026-07-14T13:05:02.000Z"
  }
}

Utilisez eventId comme clé d’idempotence. La livraison est garantie au moins une fois, sans garantie d’ordre. Le même identifiant d’événement, le même horodatage d’occurrence et les mêmes octets JSON sont réutilisés lors des tentatives.

Vérifier les signatures

Les livraisons incluent :

X-Agentkit-Event: conversation_started
X-Agentkit-Event-Id: evt_91d0a3ce-5a9d-4b67-a454-bafb9484281a
X-Agentkit-Signature: t=1784043902,v1=<hex-hmac-sha256>

Lisez le corps de la requête comme du texte brut UTF-8. Analysez t et v1, calculez un HMAC-SHA256 avec le secret du point de terminaison sur les octets exacts de t + "." + rawBody, puis comparez les empreintes avec une fonction à temps constant. N’analysez pas puis ne resérialisez pas le JSON avant la vérification. Rejetez les horodatages trop anciens selon votre politique anti-rejeu.

import { createHmac, timingSafeEqual } from 'node:crypto';

const expected = createHmac('sha256', process.env.AGENTKIT_WEBHOOK_SECRET!)
  .update(`${timestamp}.${rawBody}`, 'utf8')
  .digest('hex');

const valid = timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(v1, 'hex'));

Fiabilité et résultats

Renvoyez un statut 2xx en moins de 10 secondes. Une réponse non-2xx, un délai d’attente dépassé ou une erreur réseau déclenche cinq nouvelles tentatives après la requête initiale (six tentatives au total en général), avec le backoff de QStash. La page des paramètres affiche les 20 derniers résultats définitifs.

Un événement épuisé incrémente le compteur d’échecs consécutifs une seule fois, quel que soit le nombre de tentatives ou de rappels en double. Un abonnement n’est désactivé automatiquement qu’après au moins 10 événements épuisés consécutifs répartis sur au moins sept jours. Les propriétaires reçoivent une notification qui peut être relancée, et peuvent réactiver l’abonnement une fois le problème corrigé. Un événement réussi réinitialise le compteur.

Les URL de point de terminaison doivent utiliser HTTP ou HTTPS, être publiques, et ne peuvent pas cibler localhost, des plages IP privées ou locales au lien, ni des points de terminaison de métadonnées cloud. La production exige HTTPS. Au moment de la livraison, Agentkit résout le nom d’hôte une seule fois, exige que chaque adresse résolue soit publique et épingle la connexion à ces adresses, de sorte que le DNS rebinding ne peut pas rediriger une livraison vers une adresse interne.

Activer la planification

Le code de balayage des conversations inactives est livré désactivé. Un opérateur peut vérifier puis exécuter pnpm --filter chatbots setup:idle-conversation-webhooks après le déploiement. Cette commande crée la planification QStash de 15 minutes ; la fusion du code ne la crée ni ne l’active.

Étapes suivantes