Guide des webhooks AgentVera

Ce que fait un webhook

Chaque webhook reçoit une URL secrète. Pour une requête envoyée à cette URL, AgentVera peut :

• Ouvrir une carte kanban sur le tableau et dans la colonne de votre choix, avec des étiquettes si vous le souhaitez.
• Créer une tâche d’agent : Claude ou Codex, exécuté soit sur votre Runner, soit sur l’application de bureau qui a le projet de la carte ouvert.

Quand l’agent termine son tour, un résumé du résultat est écrit sur la carte sous forme de commentaire interne par « AgentVera ». Suivez les tâches en direct sur app.agentvera.dev/tasks.

Créer un webhook

Les propriétaires et les administrateurs de l’organisation créent les webhooks. Sur app.agentvera.dev/webhooks, cliquez sur « Yeni webhook » (nouveau webhook) et suivez ces étapes :

1. Donnez un nom au webhook.
2. Action carte : choisissez le tableau et la colonne où la carte s’ouvre.
3. Action tâche : choisissez le type d’agent (Claude ou Codex) et la cible. La cible est un Runner précis (éventuellement avec un dossier de travail) ou « Proje » (projet), c’est-à-dire l’application de bureau qui a le projet de la carte ouvert. Les tâches de projet sont toujours liées à une carte.
4. Modèle : rédigez le titre de la carte, sa description et le prompt de l’agent avec des variables {{…}}.
5. Filtre (facultatif) : ne traiter que certaines requêtes.
6. Signature (recommandée) : choisissez la vérification GitHub ou HMAC-SHA256 générique.
7. Enregistrez. L’URL du webhook et le secret de signature ne s’affichent qu’une seule fois ; copiez-les tous les deux.

Vous pouvez renouveler l’URL ou le secret plus tard ; l’ancienne URL cesse de fonctionner immédiatement.

Modèles et variables

Les variables lisent des valeurs dans la requête entrante :

• {{body.issue.title}} : les champs du corps JSON, sous forme de chemin pointé. Utilisez des nombres pour les éléments de tableau : {{body.commits.0.id}}.
• {{headers.x-github-event}} : les en-têtes de la requête, en minuscules.
• {{query.foo}} : les paramètres de requête de l’URL.

Une valeur absente devient vide ; les objets sont insérés en JSON. Les espaces dans le titre de la carte sont réduits à une seule espace et le titre est limité à 300 caractères. La description de la carte est assainie ; le prompt part à l’agent exactement tel que vous l’avez écrit.

Filtre

Un filtre exige qu’une valeur de la requête (path) soit égale à une valeur donnée ou fasse partie des valeurs que vous autorisez. Par exemple, pour ne traiter que les tickets GitHub nouvellement ouverts, indiquez body.action comme path et opened comme valeur. Les requêtes qui ne correspondent pas sont consignées comme « ignored » et n’ouvrent ni carte ni tâche.

Vérification de la signature

• GitHub : l’en-tête X-Hub-Signature-256 est vérifié avec le secret de signature.
• HMAC-SHA256 générique : la signature hexadécimale du corps est attendue dans un en-tête que vous nommez ; un préfixe sha256= est aussi accepté.

Utilisez toujours la signature quand la source la prend en charge. Pour les sources qui ne peuvent pas signer, la sécurité repose sur l’URL secrète ; renouvelez-la si elle fuit.

Exemple : des tâches à partir des tickets GitHub

1. Dans le dépôt GitHub, allez dans Settings → Webhooks → Add webhook.
2. Saisissez l’URL du webhook AgentVera comme Payload URL, application/json comme Content type et le secret de signature comme Secret.
3. Choisissez l’événement « Issues » et enregistrez.

Le modèle dans AgentVera :

Title:       {{body.issue.title}}
Description: {{body.issue.body}}
Filter:      body.action = opened
Prompt:
Ticket GitHub #{{body.issue.number}} : {{body.issue.title}}

{{body.issue.body}}

Analyse ce bug, corrige-le et lance les tests.

Sentry et autres sources JSON

Faites pointer n’importe quel service vers l’URL du webhook. Si la source peut signer, utilisez HMAC-SHA256 générique ; sinon, comptez sur l’URL secrète. Associez les champs envoyés par la source au modèle avec des variables. Pour essayer depuis votre propre système :

curl -X POST "https://app.agentvera.dev/hooks/<id>/<secret>" \
  -H "content-type: application/json" \
  -d '{"title": "Checkout page returns 500", "detail": "..."}'

Requêtes, réponses et limites

• POST uniquement ; le corps est du JSON ou un formulaire encodé, jusqu’à 1 Mo.
• 60 requêtes par minute et par webhook, 600 par minute et par IP.
• 202 : acceptée (les requêtes ignorées par le filtre reçoivent aussi 202).
• 401 : signature invalide.
• 403 : l’offre de l’organisation n’inclut pas les webhooks.
• 404 : URL erronée, webhook désactivé ou organisation suspendue (tous reçoivent la même réponse).
• 413 : corps trop volumineux. 429 : limite de débit dépassée.

Livraisons et tâches

• Chaque requête est consignée dans les livraisons du webhook avec un statut : ok, ignored, rejected ou failed, ainsi que l’indication d’une carte ou d’une tâche créée.
• Le contenu de la requête (corps, en-têtes et paramètres ; en-têtes Authorization, cookie et signature exclus) est conservé 7 jours et peut être rejoué avec le modèle actuel pendant ce temps, ce qui aide après la correction d’un modèle. Ensuite, le contenu est supprimé et le résumé reste.
• app.agentvera.dev/tasks affiche les tâches en direct : en file, prise en charge, en cours, terminée ou échouée. Les administrateurs peuvent annuler des tâches.
• Si le Runner est hors ligne, la tâche attend dans la file et est envoyée à la connexion du runner. Une tâche qui n’avance pas pendant 30 minutes retourne une fois dans la file ; la seconde fois, elle est marquée comme échouée.

Sécurité

Le contenu du webhook entre tel quel dans le prompt de l’agent. Toute personne pouvant écrire un ticket dans un dépôt pourrait tenter de donner des instructions à l’agent.

• Ne connectez que des sources et des dépôts de confiance.
• Utilisez des filtres pour restreindre les requêtes traitées.
• Sur Runner, utilisez roots pour limiter les dossiers accessibles aux agents.
• Utilisez toujours la signature quand la source la prend en charge ; l’URL est un secret, renouvelez-la si elle fuit.
• Le contenu des requêtes n’est jamais écrit dans les journaux ; la partie secrète de l’URL y est masquée.