Recevoir des déclencheurs webhook

Un webhook permet à un outil externe (Make, Zapier, votre site client, un formulaire...) de déclencher automatiquement une tâche sur un agent Agenia. Chaque webhook génère une URL unique et un secret de signature.

Créer un webhook

1. Dans la barre latérale, cliquez sur Webhooks
2. Cliquez sur Nouveau webhook
3. Donnez-lui un nom descriptif (ex : Nouveau lead formulaire contact)
4. Sélectionnez l'agent qui doit traiter les requêtes entrantes
5. Cliquez sur Créer

Agenia génère une URL de webhook unique et un secret affiché une seule fois :

https://api.agenia.io/api/v1/webhooks/inbound/wh_abc123def456

Format de la requête

Votre outil doit envoyer une requête HTTP POST au format JSON, accompagnée de deux en-têtes obligatoires :

Sans ces en-têtes valides, la requête est rejetée (401). Le timestamp protège contre les rejeux ; la signature garantit l'authenticité du corps.

Le corps JSON est transmis intégralement à l'agent comme contexte. Le titre de la tâche est dérivé du premier champ présent parmi title, event ou action.

Exemple avec curl (corps signé) :

SECRET="votre_secret"
BODY='{"title":"Nouveau lead","data":"Marie Dupont, directrice marketing, budget 5k€/mois"}'
TS=$(date +%s)
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

curl -X POST https://api.agenia.io/api/v1/webhooks/inbound/wh_abc123def456 \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Signature: sha256=$SIG" \
  -H "X-Webhook-Timestamp: $TS" \
  -d "$BODY"

Tester votre webhook

Après avoir créé le webhook, cliquez sur Tester dans la fiche du webhook. Agenia envoie une requête de test signée et vous montre la réponse de l'agent. Vérifiez que la tâche apparaît bien dans la vue Tâches.

Connecter depuis Make ou Zapier

Make et Zapier nécessitent une étape qui signe le corps en HMAC-SHA256 avant l'envoi (la signature et le timestamp sont obligatoires).

Make (ex-Integromat)

1. Ajoutez un module Tools > Set variable : timestamp = {{now}} converti en epoch secondes
2. Ajoutez un module Crypto > Create HMAC signature : algorithme SHA-256, clé = votre secret, données = le corps JSON exact
3. Ajoutez un module HTTP > Make a request :
   • URL : votre URL de webhook
   • Méthode : POST
   • En-têtes : X-Webhook-Signature = sha256={{signature}}, X-Webhook-Timestamp = {{timestamp}}
   • Body type : Raw → JSON, identique aux données signées à l'étape 2

Zapier

1. Utilisez une étape Code by Zapier (JavaScript) pour calculer le HMAC-SHA256 du corps avec crypto et générer l'epoch
2. Action Webhooks by Zapier > POST : URL du webhook, en-têtes X-Webhook-Signature et X-Webhook-Timestamp, corps identique à celui signé

Surveiller les déclenchements

Dans la fiche de votre webhook, l'onglet Historique liste les dernières requêtes reçues : date, statut (accepté / rejeté), résumé du payload et ID de la tâche créée. Les rejets (signature invalide, timestamp expiré, rate limit) y apparaissent avec leur motif.

Prochaine étape

→ Comprendre les niveaux de sécurité