需配置webhook回调功能以接收github、飞书等外部事件：一、启用gateway的webhook端口并确保可达；二、生成并安全保管含令牌的回调url；三、在各平台注册该url并完成挑战验证；四、通过hook.md定义事件路由规则；五、按需启用加密解密与签名校验。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您希望OpenClaw接收来自GitHub、飞书、企业微信等外部系统的实时事件通知，则需正确配置Webhook回调功能。该功能依赖HTTP端点监听外部POST请求，触发智能体自动响应。以下是具体配置步骤：
一、启用Gateway的Webhook服务端口
OpenClaw Gateway必须暴露一个可被外部系统访问的HTTP端点，用于接收事件推送。此端点默认绑定在本地8080端口，若部署于云环境或内网，需确保该端口对外可达且未被防火墙拦截。
1、打开OpenClaw安装目录下的gateway/config.yaml文件。
2、确认webhook:区块中enabled字段值为true。
3、检查port字段是否设置为可用端口（如8080），并确保该端口未被其他进程占用。
4、若需HTTPS支持，配置tls_cert_path与tls_key_path指向有效证书文件路径。
5、保存文件后，重启Gateway服务使配置生效。
二、生成并保护Webhook安全令牌
Webhook URL中嵌入的令牌是验证请求来源合法性的关键凭证，泄露将导致未授权事件注入。该令牌由Gateway自动生成，不可手动修改，但可重置。
1、执行命令openclaw gateway token --regenerate强制刷新当前令牌。
2、运行openclaw gateway info查看输出中的webhook_url字段，其格式为：https://your-domain.com:8080/webhook?token=abc123xyz。
3、将该完整URL复制保存至安全位置，严禁在日志、Git仓库或前端代码中明文暴露。
4、若使用反向代理（如Nginx），须确保token查询参数能透传至Gateway，禁止在代理层过滤或重写。
三、在外部系统中注册回调地址
不同平台注册方式存在差异，但核心均为将上一步获取的完整Webhook URL填入其机器人或应用配置页面的“请求URL”或“Webhook地址”字段，并完成挑战验证（Challenge）。
1、登录GitHub仓库Settings → Webhooks → Add webhook，粘贴URL，Content type选择application/json，Secret填写与OpenClaw中一致的令牌值（若平台支持）。
2、进入飞书开发者后台 → 应用管理 → 事件订阅 → 填写“请求URL”，勾选所需事件类型（如message.receive），点击“验证”按钮等待Gateway返回200 OK及正确challenge响应。
3、在企业微信自建应用 → 通讯录同步/消息接收 → 回调配置中，填入URL，Token与EncodingAESKey按Gateway输出值严格对应，保存后触发“验证URL”。
4、KOOK平台需在机器人设置中启用WebHook模式，填写Callback Url，并在收到WEBHOOK_CHALLENGE事件时，于1秒内返回原始challenge字符串，响应体为JSON格式且不含多余字段。
四、配置事件路由规则（HOOK.md）
Webhook接收到的原始事件需映射到具体Skill或Agent行为，该映射逻辑由skills/HOOK.md文件定义。该文件采用YAML语法声明事件类型与处理程序的绑定关系。
1、在skills/目录下创建或编辑HOOK.md文件。
2、添加如下结构的路由条目：
```yaml
- event: "message.receive"
source: "feishu"
handler: "feishu_reply.ts"
```
3、确保handler字段指定的TypeScript文件（如feishu_reply.ts）位于skills/子目录中，并导出默认函数接收WebhookData参数。
4、在feishu_reply.ts中解析webhookData.requestBody，提取event.message.text等字段，调用对应Skill执行业务逻辑。
5、保存后无需重启，Gateway会在检测到文件变更后自动热重载路由配置。
五、验证请求签名与解密（可选高安全场景）
当外部系统启用消息加密（如KOOK的zlib压缩+AES加密、飞书的消息加密模式）时，Gateway需主动解密并校验签名，否则将拒绝处理请求体。
1、在gateway/config.yaml中启用webhook.encryption.enabled: true。
2、根据目标平台文档，填入对应的encrypt_key（如飞书的EncodingAESKey）和verify_token。
3、对KOOK平台，若启用压缩，需在URL末尾追加?compress=0禁用zlib；若保留压缩，须在gateway启动前确保Node.js环境已安装zlib-sync依赖。
4、测试时发送一条加密消息，观察Gateway日志中是否出现Decrypted webhook payload successfully提示。
