WEBHOOK
配置 Webhook 端点
按照以下步骤在翠鸟控制台注册您的 Webhook 端点，实现事件实时推送
前提条件
开始配置前，请确保您已准备好以下内容：
- 一个可公网访问的 HTTPS 端点 URL（本地开发可使用 ngrok 临时暴露）
- 端点能够处理 HTTP POST 请求，并在 5 秒内返回 2xx 响应
- 翠鸟账号拥有 Admin 或 Owner 权限
本地开发时可使用
ngrok http 3000 生成临时公网 URL，方便调试 Webhook 请求。配置步骤
-
进入控制台登录翠鸟控制台（app.cuiniao.com），点击左侧导航栏底部的账号名称，进入账号设置页面。
-
找到 Webhook 设置在账号设置页面，选择左侧菜单中的「开发者」→「Webhook」，即可看到已配置的端点列表（首次配置时为空）。
-
添加端点 URL点击右上角「添加端点」按钮，在弹窗中填写您的 HTTPS 端点 URL，例如
https://your-server.com/webhooks/cuiniao，并添加可选的描述信息（建议填写用途说明）。 -
选择订阅事件勾选您希望接收的事件类型。建议仅订阅您实际需要处理的事件，减少无效请求压力。关于所有事件类型的详细说明，请参阅事件类型文档。
-
保存并获取 Signing Secret点击「保存」后，系统会显示一次性的 Signing Secret。请立即复制并妥善存储（此值只显示一次），用于后续的签名验证。
-
测试端点连通性保存后，点击「发送测试事件」按钮，翠鸟会向您的端点发送一条测试 Webhook 请求。若端点返回 2xx 响应，状态将显示为「正常」。
通过 API 配置
也可以通过 REST API 以编程方式管理 Webhook 端点，适合自动化部署场景：
curl -X POST https://api.cuiniao.com/v1/webhooks \
-H "Authorization: Bearer ck_live_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-server.com/webhooks/cuiniao",
"description": "生产环境线索处理",
"events": ["lead.created", "lead.status_updated"],
"active": true
}'
常见配置问题
- 端点状态显示"不可达"：检查端点 URL 是否可公网访问，防火墙是否放行了翠鸟的出口 IP 段（查看IP白名单）
- 收不到事件：确认端点已激活（状态为"活跃"），并且订阅了对应的事件类型
- 端点响应超时：翠鸟等待响应最长 5 秒，超时视为失败。建议端点收到请求后立即返回 200，将业务逻辑放入异步队列处理