Webhooks — Point d’Entrée Universel pour les Événements

Imaginez ceci : un développeur ouvre une pull request sur GitHub, et en quelques secondes, votre agent IA a déjà relu le code et posté un commentaire. Ou bien un paiement échoue sur Stripe, et votre agent notifie automatiquement votre équipe sur Telegram. C’est ça, la magie des webhooks — ils permettent à des services externes de frapper à la porte de votre agent et de lui dire : « Hé, il vient de se passer quelque chose, occupe-toi de ça. »

Qu’est-ce qu’un Webhook ?

Les webhooks, c’est un peu la sonnette de vos applications. Au lieu de vérifier en permanence si quelque chose a changé (le polling), vous attendez simplement que la sonnette retentisse. Quand GitHub, GitLab, JIRA, Stripe ou tout autre service envoie une requête HTTP POST à votre endpoint webhook, votre agent Hermes se réveille, traite l’événement et passe à l’action.

Le meilleur dans tout ça ? Votre agent peut répondre de mille façons — poster des commentaires sur les PR, envoyer des messages sur Telegram ou Discord, ou simplement journaliser le résultat pour une revue ultérieure.

Démarrage Rapide

C’est étonnamment simple de se lancer :

Activez l’adaptateur webhook via hermes gateway setup ou des variables d’environnement
Définissez des routes dans config.yaml ou créez-les dynamiquement avec hermes webhook subscribe
Pointez votre service vers http://votre-serveur:8644/webhooks/<nom-de-route>

Et voilà. Votre agent est maintenant de garde.

Configuration de la Passerelle

Vous avez deux façons d’activer les webhooks, choisissez celle qui vous convient.

Option 1 : L’assistant de configuration

hermes gateway setup

Suivez les instructions pour activer les webhooks, choisir un port et définir un secret HMAC global. L’assistant s’occupe de toute la configuration ennuyeuse pour vous.

Option 2 : Variables d’environnement

Ajoutez ces lignes à ~/.hermes/.env :

WEBHOOK_ENABLED=true
WEBHOOK_PORT=8644        # défaut
WEBHOOK_SECRET=votre-secret-global

Une fois la passerelle lancée, vérifiez qu’elle est bien vivante :

curl http://localhost:8644/health

Vous devriez voir :

{"status": "ok", "platform": "webhook"}

Configuration des Routes

Les routes sont le cœur du traitement des webhooks. Chaque route indique à votre agent comment gérer les événements d’une source spécifique. Pensez-y comme à des instructions personnalisées pour différents types de visiteurs.

Voici ce que vous pouvez configurer par route :

Propriété	Rôle
`events`	Quels types d’événements accepter (ex. `["pull_request"]`). Laissez vide pour tout accepter.
`secret`	Secret HMAC pour la validation de signature. Utilisez `"INSECURE_NO_AUTH"` uniquement pour les tests.
`profile`	Quel profil peut exécuter cette route (utile avec le multiplexage).
`prompt`	Chaîne de modèle utilisant la notation par points comme `{pull_request.title}`. Omettre pour envoyer le payload JSON complet.
`filters`	Conditions déclaratives pour ignorer les payloads indésirables avant que l’agent ne s’exécute.
`script`	Un script de filtre/transformation qui peut modifier le payload avant le templating.
`skills`	Quelles compétences charger pour cette exécution d’agent.
`toolsets`	Quels outils l’agent peut utiliser (remplace le toolset webhook par défaut).
`deliver`	Où envoyer la réponse : `github_comment`, `telegram`, `discord`, `slack`, `log`, et plus encore.
`deliver_extra`	Détails de livraison supplémentaires comme le nom du dépôt ou l’ID du chat.
`deliver_only`	Ignorer complètement l’agent et livrer le prompt rendu tel quel. Zéro coût LLM !

Un Exemple Concret

Regardons une configuration pratique. Voici une route qui relit les pull requests :

platforms:
  webhook:
    enabled: true
    extra:
      port: 8644
      secret: "secret-de-secours-global"
      routes:
        github-pr:
          events: ["pull_request"]
          secret: "secret-webhook-github"
          prompt: |
            Relisez cette pull request :
            Dépôt : {repository.full_name}
            PR #{number} : {pull_request.title}
            Auteur : {pull_request.user.login}
            URL : {pull_request.html_url}
            URL du diff : {pull_request.diff_url}
            Action : {action}
          skills: ["github-code-review"]
          deliver: "github_comment"
          deliver_extra:
            repo: "{repository.full_name}"
            pr_number: "{number}"

Et voici une route qui envoie une notification Telegram uniquement quand quelqu’un pousse sur la branche principale :

        deploy-notify:
          events: ["push"]
          secret: "secret-deploy"
          prompt: "Nouveau push sur {repository.full_name} branche {ref} : {head_commit.message}"
          filters:
            - field: "ref"
              equals: "refs/heads/main"
          deliver: "telegram"

Filtrage Intelligent

La fonctionnalité filters est particulièrement pratique. Les fournisseurs envoient souvent un flot d’événements, mais vous ne vous intéressez qu’à quelques-uns. Les filtres vous permettent d’ignorer le bruit avant même que votre agent ne se réveille. Les payloads non correspondants reçoivent une réponse polie {"status":"ignored","reason":"filter"} avec un code HTTP 200 — aucun calcul gaspillé, aucun appel LLM inutile.

Mode Livraison Directe

Voici une astuce maligne : définissez deliver_only: true et votre agent ne s’exécute jamais du tout. Le modèle de prompt rendu devient le message littéral qui est livré. Cela signifie une livraison en moins d’une seconde avec zéro coût LLM. Parfait pour les notifications simples qui n’ont pas besoin de raisonnement IA.

Note de Sécurité

Rappelez-vous : authentifié ne veut pas dire fiable. Les champs de payload provenant des webhooks sont des données non fiables. Validez et assainissez toujours tout ce que vous utilisez dans les prompts ou les modèles. Votre agent doit traiter le contenu des webhooks comme une entrée utilisateur — avec un scepticisme sain.

En Résumé

Les webhooks transforment votre agent Hermes en assistant réactif qui réagit au monde en temps réel. Que vous automatisiez des revues de code, envoyiez des notifications de déploiement ou construisiez des workflows complexes pilotés par les événements, l’adaptateur webhook rend tout cela possible avec seulement quelques lignes de YAML.