Webhook 参考
事件负载结构与 Webhook 配置
Webhook 参考
当 Umbrella 中发生事件时，Webhook 会向您的端点发送 HTTP POST 请求，因此您无需轮询 API 来获取变更。
设置
- 前往 仪表板 > 设置 > 集成 > Webhook
- 点击 添加 Webhook 端点
- 输入您的 HTTPS 端点 URL
- 选择您要接收的事件
- 保存并妥善保管签名密钥（仅显示一次）
您的端点必须接受 POST 请求，在 30 秒内返回 2xx 状态码，并接受 application/json。
事件类型
保单事件
| 事件 | 说明 |
|---|---|
policy.created | 顾客购买了保修 |
policy.activated | 保单状态变为生效 |
policy.expired | 保单已到结束日期 |
policy.cancelled | 保单已取消（退款或商家操作） |
policy.voided | 保单已作废（订单取消或拒付） |
索赔事件
| 事件 | 说明 |
|---|---|
claim.submitted | 顾客提交了索赔 |
claim.approved | 商家批准了索赔 |
claim.denied | 商家拒绝了索赔 |
claim.resolved | 索赔已全部处理完毕 |
claim.evidence_uploaded | 索赔已附上证据 |
注册事件
| 事件 | 说明 |
|---|---|
registration.submitted | 已提交产品注册 |
registration.approved | 注册已批准 |
registration.denied | 注册已拒绝 |
保修事件
| 事件 | 说明 |
|---|---|
warranty.created | 已创建新的保修计划 |
warranty.updated | 保修计划已修改 |
warranty.activated | 保修计划已启用 |
warranty.deactivated | 保修计划已停用 |
负载结构
每个 Webhook 都采用以下封装格式：
{
"id": "evt_a1b2c3d4e5f6",
"type": "claim.submitted",
"timestamp": "2025-03-15T14:30:00.000Z",
"apiVersion": "1.3.9",
"orgId": "org_xyz789",
"data": { ... }
}id— 唯一事件 ID（用于去重）type— 事件类型timestamp— 事件发生的时间data— 特定于事件的负载，包含相关资源的详细信息（保单、索赔、注册等）
签名验证
每个请求都包含 X-Umbrella-Signature 请求头，其值为请求体的 HMAC-SHA256 哈希。请在处理事件之前先进行验证。
const crypto = require('crypto');
function verifyWebhookSignature(payload, signature, secret) {
const expected = crypto
.createHmac('sha256', secret)
.update(payload, 'utf8')
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expected)
);
}重试策略
投递失败（非 2xx、超时、连接错误）时，系统会按指数退避方式重试：
| 尝试 | 延迟 |
|---|---|
| 第 2 次 | 1 分钟 |
| 第 3 次 | 5 分钟 |
| 第 4 次 | 30 分钟 |
| 第 5 次 | 2 小时 |
| 第 6 次 | 6 小时 |
| 第 7 次（最后一次） | 12 小时 |
连续 7 次尝试失败后，该投递会被标记为失败。若返回 410 Gone 响应，该端点将被永久停用。
测试
- 前往 仪表板 > 设置 > 集成 > Webhook
- 点击您的端点，然后点击 发送测试事件
- 选择一种事件类型并查看投递结果
Webhook 详情页面还会显示最近投递的日志，包括状态码和耗时。
注意 请立即返回 200，并以异步方式处理事件，以免超时。由于重试可能会多次投递同一事件，请使用事件的
id 进行去重。
