Webhooks Hermes Agent : declenchement evenementiel, guide complet

Introduction

Les webhooks permettent a des services externes (GitHub, GitLab, Stripe, CI/CD, monitoring) de declencher une execution de Hermes Agent en envoyant une requete HTTP POST. Contrairement aux crons qui s'executent a heure fixe, les webhooks reagissent a des evenements en temps reel.

Cette page est le guide de reference pour la configuration et l'utilisation des webhooks. Pour une vue d'ensemble des trois mecanismes d'automatisation, consultez Automatiser avec Hermes Agent.

Question couverte

q-106: Comment declencher Hermes Agent depuis un webhook ?

La mise en place d'un webhook se fait en trois etapes.

Etape 1 : Activer la plateforme webhook

Le serveur webhook est integre au gateway Hermes Agent. Activez-le via hermes gateway setup ou manuellement dans ~/.hermes/config.yaml :

platforms:
  webhook:
    enabled: true
    extra:
      port: 8644
      secret: "votre-secret-hmac-genere"

Demarrez le gateway :

hermes gateway run

Verifiez que le serveur ecoute :

curl http://localhost:8644/health
# Retourne {"status": "ok"}

Etape 2 : Creer un abonnement webhook

hermes webhook subscribe github-issues \
  --events "issues" \
  --prompt "Nouvelle issue GitHub #{issue.number}: {issue.title}\n\nAction: {action}\nAuteur: {issue.user.login}\n\n{issue.body}\n\nAnalyse cette issue et propose un triage." \
  --deliver telegram \
  --deliver-chat-id "-100123456789"

La commande retourne une URL de webhook et un secret HMAC. Configurez votre service externe (GitHub, GitLab, etc.) pour envoyer des POST a cette URL avec le secret.

Etape 3 : Configurer le service emetteur

Sur GitHub, allez dans Settings > Webhooks > Add webhook :

• Payload URL : l'URL retournee par hermes webhook subscribe
• Content type : application/json
• Secret : le secret HMAC retourne
• Events : selectionnez les evenements qui vous interessent (ex: "Issues")

Templates de prompt

Les prompts supportent la notation {payload.champ} pour acceder aux champs du JSON recu :

• {issue.title} : titre d'une issue GitHub
• {pull_request.user.login} : auteur d'une PR
• {data.object.amount} : montant d'un paiement Stripe
• {alert.severity} : severite d'une alerte monitoring

Si aucun prompt n'est specifie, le JSON complet est injecte dans le prompt de l'agent.

Securite

Chaque abonnement recoit un secret HMAC-SHA256 genere automatiquement. Le gateway valide la signature de chaque requete entrante. Les abonnements sont persistes dans ~/.hermes/webhook_subscriptions.json.

Filtrage des evenements

Pour les services qui emettent beaucoup d'evenements, vous pouvez filtrer les payloads avant qu'ils n'atteignent l'agent :

hermes webhook subscribe todoist-hermes \
  --prompt "Tache modifiee: {payload.content}" \
  --script "filtre-todoist.py" \
  --deliver telegram --deliver-chat-id "12345"

Le script (dans ~/.hermes/scripts/) recoit le JSON sur stdin. S'il retourne une sortie vide, [SILENT], ou un code de sortie non nul, le webhook est ignore silencieusement.

Livraison directe sans agent (--deliver-only)

Pour les cas ou vous voulez simplement transmettre une notification sans cout LLM :

hermes webhook subscribe alerte-monitoring \
  --deliver telegram \
  --deliver-chat-id "123456789" \
  --deliver-only \
  --prompt "🚨 Alerte: {alert.name}\nSeverite: {alert.severity}\n{alert.message}"

Le prompt est rendu comme message litteral et livre directement, sans passer par l'agent.

Cas d'usage typiques

Test et depannage

Tester un webhook sans evenement reel :

hermes webhook test <nom>

Verifier les logs du gateway :

grep webhook ~/.hermes/logs/gateway.log | tail -20

Sources

• Documentation officielle Hermes Agent (https://hermes-agent.nousresearch.com/docs/)
• Guide Automation Blueprints (https://hermes-agent.nousresearch.com/docs/guides/automation-blueprints)
• Guide Webhook GitHub PR Review (https://hermes-agent.nousresearch.com/docs/guides/webhook-github-pr-review)
• CLI commands reference (https://hermes-agent.nousresearch.com/docs/reference/cli-commands)
• Depot NousResearch/hermes-agent, commit b4f8c491

Liens internes proposes

• Automatiser avec Hermes Agent
• Cron Hermes Agent
• Canaux et gateway
• Configurer Hermes Agent
• FAQ
• Sources