Webhooks

webhook 通道是一个通用的入站/出站 HTTP 适配器。它在你选择的端口上运行自己的内嵌 HTTP 服务器，接受 JSON 格式的消息，将其交给代理，并（可选地）将代理的回复 POST 到你指定的 URL。可将其用作任何能够生成 HTTP POST 请求的系统的通用适配器。

与网关的 /webhook 端点不同。 网关服务有其自己的 POST /webhook，用于已配对的客户端通过 HTTP 访问代理，该端点位于 [gateway] 下，并在运维 → 网络部署中进行了说明。本页仅介绍 [channels.webhook] 通道。

入站

该通道绑定 0.0.0.0:{port} 并路由 POST {listen_path}。

请求正文（JSON）：

{
  sender: alice,
  "内容": "你好，agent。",
  "thread_id": optional-conversation-id
}

sender：必填，用作消息的发送方身份。
content：必填，传递给代理的用户消息。内容为空将返回 400。
thread_id：可选。如果设置，agent 的回复将定向到同一线程；否则回复将定向到 sender。

成功时返回 200 OK。JSON 格式错误或 content 为空时返回 400。背压（通道队列已满）时返回 503。

签名验证

当设置 secret 后，每个入站请求都必须携带 X-Webhook-Signature 标头：

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

通道计算 HMAC-SHA256(secret, raw_body)，将其进行十六进制编码，并与请求头的值进行比较（解码前会去除 sha256= 前缀）。不匹配或缺少请求头时返回 401。

当 secret 未设置时，该通道拒绝启动（监听器在启动时终止并返回错误，提示操作员配置一个）。已启用的 webhook 通道始终需要配置 secret。这是刻意的快速失败机制：一个未经身份验证、具备代理访问权限的 webhook 监听器是一个不应存在于任何部署中的开放入口。

重大变更。 以前在反向代理后方或绑定到私有网络中以无密钥方式运行监听器的部署，现在必须在 [channels.webhook.<alias>].secret 中配置 secret。无密钥回退路径已移除：已启用的 webhook 监听器被视为任何部署拓扑都不应暴露的无条件风险。处于此情况的运维人员应设置 secret，并可选择将监听器保留在现有反向代理后方，或继续绑定到私有网络；两种方式均可，secret 才是现在的关键所在。

出站

当设置了 send_url 时，每个智能体回复都会作为 HTTP 请求发送到该 URL：

{send_method} {send_url}
Authorization: {auth_header}    # 仅当设置了 auth_header 时
Content-Type: application/json

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

send_method 为 POST（默认）或 PUT。任何其他值都将回退为 POST。
auth_header 会作为 Authorization 头的值原样发送，请自行包含方案（例如 Bearer xyz、Basic dXNlcjpwYXNz）。
recipient 为空时将被省略。
非 2xx 响应会在日志中引发错误；代理回复将被视为失败。

当 send_url 未设置时，agent 的回复会被静默丢弃（仅在 debug 级别记录日志）。对于“发送后即忘“的入站流程而言，这是正确的配置，因为响应会通过其他渠道传递。

公开暴露

该通道直接绑定到 0.0.0.0。若要将其暴露到公网：

反向代理：在 nginx / Caddy / Traefik 上终止 TLS，并代理到通道的端口。参见 Operations → Network deployment。
隧道：配置 [tunnel]（ngrok、cloudflare 或 tailscale），守护进程会在启动通道的同时建立隧道。
仅本地：在专用网络内运行，让你的生产者直接访问 LAN/环回地址。

始终将公开暴露与 secret 配对使用。未经身份验证的 Webhook 监听器相当于向代理开放的入口。

当设置了 send_url 时，出站投递会对临时性故障、网络错误、HTTP 429 和 HTTP 5xx 进行重试，采用指数退避（±25% 抖动），并受 retry_max_delay_ms 限制上限。非 429 的 4xx 响应会立即失败，不进行重试。当服务器在 429 或 503 时返回 Retry-After 标头时，将遵循该值，且同样受 retry_max_delay_ms 钳制。设置 max_retries = 0 表示发送后即不再关心结果。

另见

运维 → 网络部署：TLS 终止、隧道，以及网关独立的 /webhook
通道 → 概述

Keyboard shortcuts

ZeroClaw Docs