Webhooks

Le canal webhook est un adaptateur HTTP générique entrant/sortant. Il exécute son propre serveur HTTP intégré sur un port de votre choix, accepte les messages au format JSON, les transmet à l’agent et (éventuellement) envoie via POST les réponses de l’agent à une URL que vous spécifiez. Utilisez-le comme adaptateur universel pour tout système capable de produire une requête HTTP POST.

À ne pas confondre avec l’endpoint /webhook de la passerelle. Le service de passerelle possède son propre POST /webhook pour les clients appairés qui accèdent à l’agent via HTTP ; il se trouve sous [gateway] et est décrit dans Operations → Network deployment. Cette page documente uniquement le canal [channels.webhook].

Configuration

zeroclaw config set channels.webhook.<alias>.auth_header    # entrée masquée, stockée chiffrée

export ZEROCLAW_channels__webhook__<alias>__auth_header=

zeroclaw config set channels.webhook.<alias>.excluded_tools <value>

export ZEROCLAW_channels__webhook__<alias>__excluded_tools=

zeroclaw config set channels.webhook.<alias>.listen_path <value>

export ZEROCLAW_channels__webhook__<alias>__listen_path=

zeroclaw config set channels.webhook.<alias>.max_retries <value>

export ZEROCLAW_channels__webhook__<alias>__max_retries=

zeroclaw config set channels.webhook.<alias>.port <value>

export ZEROCLAW_channels__webhook__<alias>__port=

zeroclaw config set channels.webhook.<alias>.reply_min_interval_secs <value>

export ZEROCLAW_channels__webhook__<alias>__reply_min_interval_secs=

zeroclaw config set channels.webhook.<alias>.reply_queue_depth_max <value>

export ZEROCLAW_channels__webhook__<alias>__reply_queue_depth_max=

zeroclaw config set channels.webhook.<alias>.retry_base_delay_ms <value>

export ZEROCLAW_channels__webhook__<alias>__retry_base_delay_ms=

zeroclaw config set channels.webhook.<alias>.retry_max_delay_ms <value>

export ZEROCLAW_channels__webhook__<alias>__retry_max_delay_ms=

zeroclaw config set channels.webhook.<alias>.secret    # entrée masquée, stockée chiffrée

export ZEROCLAW_channels__webhook__<alias>__secret=

zeroclaw config set channels.webhook.<alias>.send_method <value>

export ZEROCLAW_channels__webhook__<alias>__send_method=

zeroclaw config set channels.webhook.<alias>.send_url <value>

export ZEROCLAW_channels__webhook__<alias>__send_url=

Référence complète des champs : référence de configuration.

Entrant

Le canal se lie à 0.0.0.0:{port} et achemine POST {listen_path}.

Corps de la requête (JSON) :

{
  "sender": alice,
  "contenu": « Bonjour, agent. »,
  "thread_id": "optional-conversation-id"
}

• sender : requis, utilisé comme identité d’expéditeur du message.
• content : requis, le message utilisateur transmis à l’agent. Un contenu vide renvoie 400.
• thread_id : facultatif. S’il est défini, la réponse de l’agent cible le même fil de discussion ; sinon, les réponses ciblent sender.

En cas de succès, renvoie 200 OK. Un JSON mal formé ou un content vide renvoie 400. La contre-pression (file d’attente du canal pleine) renvoie 503.

Vérification de la signature

Lorsque secret est défini, chaque requête entrante doit comporter un en-tête X-Webhook-Signature :

X-Webhook-Signature: sha256=<hex-encoded HMAC-SHA256 of the raw body>

Le canal calcule HMAC-SHA256(secret, raw_body), l’encode en hexadécimal, puis le compare à la valeur de l’en-tête (le préfixe sha256= est retiré avant le décodage). En cas de non-correspondance ou d’en-tête manquant, 401 est renvoyé.

Lorsque secret n’est pas défini, le canal refuse de démarrer (l’écouteur s’arrête au démarrage avec une erreur invitant l’opérateur à en configurer un). Un canal webhook activé nécessite toujours un secret configuré. Il s’agit d’un échec rapide délibéré : un écouteur webhook non authentifié disposant d’un accès à l’agent constitue un point d’entrée ouvert qui ne devrait exister dans aucun déploiement.

Changement majeur. Les déploiements qui exécutaient précédemment le listener sans secret derrière un reverse proxy ou lié à un réseau privé doivent maintenant configurer un secret dans [channels.webhook.<alias>].secret. Le chemin de repli sans secret est supprimé : un listener webhook activé est considéré comme un risque inconditionnel auquel aucune topologie de déploiement ne devrait être exposée. Les opérateurs dans cette situation doivent définir un secret et soit conserver le listener derrière leur reverse proxy existant, soit continuer à se lier à un réseau privé ; l’un ou l’autre convient, le secret est désormais l’élément porteur.

Sortant

Lorsque send_url est défini, chaque réponse de l’agent est transmise sous forme de requête HTTP à cette URL :

{send_method} {send_url}
Authorization: {auth_header}    # uniquement si auth_header est défini
Content-Type: application/json

{
  "content": "agent reply text",
  "thread_id": "optional thread id",
  "recipient": "optional recipient id"
}

• send_method est POST (par défaut) ou PUT. Toute autre valeur revient à POST.
• auth_header est envoyé tel quel comme valeur de l’en-tête Authorization, incluez vous-même le schéma (p. ex. Bearer xyz, Basic dXNlcjpwYXNz).
• recipient est omis lorsqu’il est vide.
• Les réponses non-2xx génèrent une erreur dans les journaux ; la réponse de l’agent est considérée comme ayant échoué.

Lorsque send_url n’est pas défini, les réponses de l’agent sont ignorées silencieusement (consignées au niveau debug). Il s’agit de la configuration appropriée pour les flux entrants de type « fire-and-forget » où la réponse est transmise par un autre canal.

Exposition publique

Le canal se lie directement à 0.0.0.0. Pour l’exposer sur l’Internet public :

1. Reverse proxy : terminer TLS au niveau de nginx / Caddy / Traefik et faire un proxy vers le port du canal. Voir Opérations → Déploiement réseau.
2. Tunnel : configurez [tunnel] (ngrok, cloudflare ou tailscale) et le daemon active le tunnel en même temps que le canal.
3. Local uniquement : exécutez dans un réseau privé et faites en sorte que votre producteur accède directement à l’adresse LAN/loopback.

Associez toujours l’exposition publique à un secret. Un écouteur de webhook non authentifié constitue un point d’entrée ouvert vers l’agent.

Nouvelles tentatives sortantes

Lorsque send_url est défini, la livraison sortante réessaie les échecs transitoires, les erreurs réseau, les réponses HTTP 429 et HTTP 5xx, avec un backoff exponentiel (gigue de ±25 %) plafonné par retry_max_delay_ms. Les réponses 4xx autres que 429 échouent immédiatement sans nouvelle tentative. Lorsque le serveur renvoie un en-tête Retry-After sur 429 ou 503, cette valeur est respectée et également plafonnée par retry_max_delay_ms. Définir max_retries = 0 correspond à un mode « fire-and-forget » (envoyer et oublier).

Voir aussi

• Opérations → Déploiement réseau : terminaison TLS, tunnels, le /webhook séparé de la passerelle
• Chaînes → Vue d’ensemble