🪝 OpenClaw Webhooks完全指南

世界上有一种等待叫Webhook——你不知道它什么时候来，但你知道它一定会来...

📚 什么是Webhook？

Webhook是一种"反向API"——不是你去请求数据，而是服务器主动推送数据给你。

在OpenClaw中，Webhook可以用于：

  • 接收外部事件：GitHub推送、支付通知、表单提交
  • 触发Agent工作流：收到Webhook后自动执行任务
  • 实时集成：与其他系统建立即时连接

⚙️ Webhook配置

基础配置

在OpenClaw Gateway中配置Webhook端点：

# config.yaml
webhooks:
  enabled: true
  port: 8080
  endpoints:
    - path: /github-webhook
      secret: your_webhook_secret
      handler: github_push
    - path: /payment-webhook
      secret: payment_secret
      handler: payment_received

Secret验证

为了安全，Webhook应该验证请求签名：

# 验证GitHub Webhook签名
import hmac
import hashlib

def verify_signature(payload, signature, secret):
    expected = 'sha256=' + hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

⚙️ 处理Webhook事件

GitHub Webhook示例

{
  "handler": "github_push",
  "action": "process_webhook",
  "payload": {
    "ref": "refs/heads/main",
    "repository": {
      "name": "my-repo",
      "url": "https://github.com/user/my-repo"
    },
    "commits": [...]
  }
}

Agent响应流程

# 收到Webhook后的处理逻辑
1. 验证签名
2. 解析payload
3. 根据事件类型执行对应操作
   - push事件 → 拉取代码 → 运行测试
   - pr事件 → 代码审查 → 评论反馈
   - issue事件 → 分类 → 分配处理

💡 最佳实践

  • 验证签名：始终验证Webhook请求的签名
  • 幂等处理：同一事件可能发送多次，确保处理幂等
  • 异步处理：Webhook响应要快，重活放后台
  • 错误重试：配置失败重试机制
  • 日志记录：记录所有Webhook请求便于排查

🚀 实战案例

案例1：GitHub自动部署

# 收到push事件后自动部署
if webhook.event == "push" and webhook.ref == "refs/heads/main":
    exec("cd /var/www/app && git pull")
    exec("cd /var/www/app && npm install")
    exec("cd /var/www/app && npm run build")
    exec("sudo systemctl restart app")
    message({"action": "send", "message": "部署完成"})

案例2：支付通知处理

# 收到支付Webhook后处理订单
if verify_signature(payload, signature, secret):
    order_id = payload.order_id
    status = payload.status
    
    if status == "completed":
        update_order_status(order_id, "paid")
        send_confirmation_email(order_id)
        notify_admin(f"新订单: {order_id}")

🔗 相关资源