API REFERENCE
Webhook 事件 API
通过 API 管理 Webhook 端点配置，并查询 Webhook 投递记录与重试状态
Webhook 端点管理
通过控制台或 API 注册 Webhook 端点，翠鸟将在事件触发时向您的端点 POST 事件数据。
| 方法 | 路径 | 描述 |
|---|---|---|
GET | /v1/webhooks | 列出所有已注册的 Webhook 端点 |
POST | /v1/webhooks | 注册新的 Webhook 端点 |
GET | /v1/webhooks/{id} | 查询指定端点配置详情 |
PUT | /v1/webhooks/{id} | 更新端点 URL 或订阅事件 |
DELETE | /v1/webhooks/{id} | 删除 Webhook 端点 |
POST | /v1/webhooks/{id}/test | 向端点发送一条测试事件 |
GET | /v1/webhooks/{id}/deliveries | 查询该端点的投递历史记录 |
注册 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",
"resource.published"
],
"active": true
}'
响应示例
{
"id": "wh_4kRp9nZxLm",
"url": "https://your-server.com/webhooks/cuiniao",
"signing_secret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
"events": ["lead.created", "lead.status_updated", "resource.published"],
"active": true,
"created_at": "2024-03-15T10:00:00Z"
}
重要：请妥善保存
signing_secret，它仅在创建时返回一次。用于验证每次 Webhook 请求的真实性，详见签名验证文档。投递记录与重试
翠鸟会保留每条 Webhook 事件的投递记录，包括请求内容、响应状态及重试历史。
# 查询端点最近的投递记录
curl "https://api.cuiniao.com/v1/webhooks/wh_4kRp9nZxLm/deliveries?limit=10" \
-H "Authorization: Bearer ck_live_xxxxxxxxxxxx"
{
"deliveries": [
{
"delivery_id": "del_7wXq2mPr",
"event_type": "lead.created",
"status": "success",
"http_status": 200,
"attempted_at": "2024-03-15T09:15:00Z",
"duration_ms": 234,
"retry_count": 0
},
{
"delivery_id": "del_8vYp3nQs",
"event_type": "lead.created",
"status": "failed",
"http_status": 503,
"attempted_at": "2024-03-15T09:20:00Z",
"next_retry_at": "2024-03-15T09:25:00Z",
"retry_count": 1
}
]
}
投递失败时，翠鸟按指数退避策略自动重试：1分钟、5分钟、30分钟、2小时、12小时，共重试5次。也可通过 POST /v1/webhooks/deliveries/{id}/retry 手动触发重试。
事件类型列表
以下是所有可订阅的 Webhook 事件，更多详情请参阅 事件类型说明。
lead.created— 新线索创建（访客提交表单）lead.status_updated— 线索状态变更lead.score_changed— 线索评分变化超过10分resource.published— 内容资源发布上线resource.archived— 内容资源归档cta.form_submitted— CTA 表单提交visitor.identified— 匿名访客身份识别成功