Webhook 管理位于 /api/v2/webhooks。将 webhook URL 和签名材料视为机密。
开始前
创建具有最低工作区访问权限的 API 密钥，并确定集成需要的事件系列。
步骤
- 打开 Settings → Integrations。
- 创建或选择 webhook 目标。
- 记录已配置的事件 ID 和端点状态。
- 向非生产接收端发送测试请求。
- 在启用生产处理前，确认响应并检查投递尝试。
保持接收端幂等。保存事件标识符，验证 payload 后再确认接收。不要假设应用内部的每个事件都是受支持的客户 webhook。
配置和验证 webhook
- 创建接受事件 payload 的端点，在返回成功响应前保存事件标识符。
- 在 Settings → Integrations 中使用显示的 Name、Target hook URL、Event type，以及可选的 Campaign 或 custom interest value 创建 webhook。
- 保存目标并打开它，使用 Test。确认接收端记录事件，API 返回
success: true。 - 在 Webhook events 中检查
status_code、success、retry_count、will_retry和error_message。 - URL 变化时删除或更新目标；删除目标不会清除历史投递尝试。
使用游标分页（limit 和 starting_after）读取事件历史。将重试视为至少一次投递，并让 consumer 保持幂等。
失败恢复
接收端返回 4xx 通常需要修复 payload 或身份验证；5xx 或超时可以使用有界 backoff 重试。在 Webhook events 中确认下一次尝试，并使用事件 ID 和脱敏状态升级。
Webhook 字段参考
| 字段 | 必填 | 含义 |
|---|---|---|
| Name | 是 | 工作区中的目标标签。 |
| Target hook URL | 是 | 接收投递的 HTTPS 端点。 |
| Event type | 是 | event-types 端点返回的事件标识符。 |
| Campaign | 可选 | 选择后将事件限制到一个活动。 |
| Custom interest value | 有条件 | 所选事件是自定义兴趣标签时必填。 |
验证投递
执行 Test 后，确认接收端保存事件 ID、返回成功响应，并且重试时没有创建重复记录。在 Webhook events 中检查 status_code、success、retry_count、will_retry、error_message 和 timestamp_next_retry。