API Webhooks

L’API Webhooks vous permet de vous abonner à des événements de façon programmatique. Utilisez-la pour des déclencheurs instantanés façon Zapier, ou pour des intégrations personnalisées qui ont besoin de notifications en temps réel.

Remarque : l’API Webhooks nécessite un forfait Hobby ou supérieur, avec facturation active.

Points de terminaison

Créer un abonnement

POST /api/v1/webhooks/subscribe

Corps de la requête

{
  "event": "form_submission",
  "targetUrl": "https://your-server.com/webhook",
  "chatbotId": "123e4567-e89b-12d3-a456-426614174000"
}

Paramètres

Réponse

Succès (201) :

{
  "id": "subscription-uuid"
}

Exemple

curl -X POST 'https://your-domain.com/api/v1/webhooks/subscribe' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "event": "form_submission",
    "targetUrl": "https://hooks.zapier.com/hooks/catch/123456/abcdef",
    "chatbotId": "123e4567-e89b-12d3-a456-426614174000"
  }'

Supprimer un abonnement

DELETE /api/v1/webhooks/subscribe/[id]

Réponse

Succès (200) : Renvoie une réponse vide avec le statut 200.

Exemple

curl -X DELETE 'https://your-domain.com/api/v1/webhooks/subscribe/sub_abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Lister les agents

Récupérez la liste des agents disponibles pour un abonnement :

GET /api/v1/chatbots

Réponse

{
  "chatbots": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Support Bot",
      "url": "https://your-domain.com/chat/support-bot"
    }
  ]
}

Charge utile du webhook

Lorsqu’un événement se produit, nous envoyons une requête POST à votre URL cible :

Événement de soumission de formulaire

{
  "event": "form_submission",
  "eventId": "evt_91d0a3ce-5a9d-4b67-a454-bafb9484281a",
  "data": {
    "id": "lead-uuid",
    "chatbotId": "123e4567-e89b-12d3-a456-426614174000",
    "name": "John Smith",
    "email": "[email protected]",
    "phone": "+1234567890",
    "conversationId": "conv_abc123",
    "createdAt": "2025-01-10T12:00:00Z"
  },
  "timestamp": "2025-01-10T12:00:00Z"
}

En-têtes

Nous incluons ces en-têtes à chaque envoi :

Content-Type: application/json
User-Agent: AgentkitWebhook/2.0
X-Agentkit-Event: form_submission
X-Agentkit-Event-Id: evt_91d0a3ce-5a9d-4b67-a454-bafb9484281a
X-Agentkit-Signature: t=<unix-seconds>,v1=<hex-hmac-sha256>

Vérifiez la signature par rapport au corps brut exact de la requête, encodé en UTF-8, avant d’analyser le JSON. Voir Sécurité des webhooks pour la procédure de signature et le catalogue des charges utiles.

Exigences liées à l’URL

Sécurité

En production, l’URL d’un abonnement doit utiliser HTTPS. En dehors de la production, HTTP est également accepté — mais seules les URL http: et https: sont jamais autorisées, et chaque URL doit en plus réussir un contrôle de destination publique portant sur l’URL elle-même, qui rejette localhost et les noms d’hôte de boucle locale similaires, les adresses privées et locales au lien littérales, ainsi que les points de terminaison de métadonnées cloud.

Voir Sécurité des webhooks pour la liste complète des restrictions de destination ; c’est la description canonique de cette règle.

Validation

L’URL est vérifiée lors de la création de l’abonnement ; les URL qui échouent aux contrôles ci-dessus sont rejetées avec une erreur 400 dont le message précise l’exigence de production. Le contrôle examine l’URL telle qu’elle est écrite — il ne résout pas les noms d’hôte, alors pointez votre abonnement vers le point de terminaison public où vous voulez réellement recevoir les événements. Au moment de la livraison, le nom d’hôte est résolu une seule fois, chaque adresse résolue doit être publique et la connexion est épinglée à ces adresses : un nom d’hôte qui se résout en une adresse privée ou interne (même si elle change entre la résolution et la connexion) n’est jamais contacté ; la tentative est enregistrée comme target_blocked.

Fiabilité

Exigences côté réponse

Votre point de terminaison doit :

• Renvoyer un statut 2xx en moins de 10 secondes
• Gérer les envois en double (idempotence)

Gestion des échecs

• Les envois en échec sont retentés cinq fois après la requête initiale
• Un événement épuisé incrémente une fois le compteur d’échecs consécutifs
• Au moins 10 événements épuisés sur une période de sept jours désactivent automatiquement un abonnement
• Les propriétaires peuvent réparer et réactiver les abonnements depuis les paramètres des webhooks
• La livraison se fait au moins une fois ; utilisez eventId pour gérer l’idempotence et ne présumez pas de l’ordre des événements

Réponses d’erreur

Intégration Zapier

Ces points de terminaison alimentent notre intégration Zapier. Quand vous connectez Agentkit à Zapier :

1. Zapier appelle /api/v1/auth pour vérifier votre clé API
2. Zapier appelle /api/v1/chatbots pour lister vos agents
3. Quand vous activez un déclencheur, Zapier appelle /api/v1/webhooks/subscribe
4. Les événements sont envoyés à l’URL du webhook de Zapier
5. Quand vous le désactivez, Zapier appelle DELETE sur l’abonnement

Pour intégrer sans écrire de code, utilisez directement Zapier plutôt que ces API.

Configurer Zapier →

Exemple de code

Gestionnaire d’abonnements Node.js

class WebhookManager {
  constructor(apiKey, baseUrl) {
    this.apiKey = apiKey;
    this.baseUrl = baseUrl;
  }

  async subscribe(chatbotId, targetUrl, event = 'form_submission') {
    const response = await fetch(`${this.baseUrl}/api/v1/webhooks/subscribe`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ event, targetUrl, chatbotId }),
    });

    if (!response.ok) {
      throw new Error(`Subscribe failed: ${response.status}`);
    }

    return response.json();
  }

  async unsubscribe(subscriptionId) {
    const response = await fetch(
      `${this.baseUrl}/api/v1/webhooks/subscribe/${subscriptionId}`,
      {
        method: 'DELETE',
        headers: { 'Authorization': `Bearer ${this.apiKey}` },
      },
    );

    return response.ok;
  }
}

Étapes suivantes

• Configurer la collecte de prospects pour générer des événements
• Configurer les webhooks dans l’interface pour une configuration depuis le tableau de bord
• Vous connecter à Zapier pour plus de 5 000 intégrations