Webhook

Webhook 配置

发生保修事件时，Umbrella 会向您的外部系统发送 Webhook 通知。使用 Webhook 可与您的 CRM、客服系统、分析工具或后端服务集成。

---

事件类型

保单事件

事件	说明
policy.created	保修保单已创建（含保修的订单已完成）
policy.activated	保单已激活（付款已确认）
policy.expired	保单已到期
policy.cancelled	保单已取消（退款或订单取消）
policy.updated	保单已更新（状态或元数据变更）

索赔事件

事件	说明
claim.created	提交了新索赔
claim.updated	索赔状态已变更
claim.approved	索赔已批准
claim.denied	索赔已拒绝
claim.resolved	索赔已处理（替换品已发货或已退款）

订单事件

事件	说明
order.warranty_attached	保修已附加到订单行项目
order.warranty_removed	保修已从订单中移除
order.post_purchase_completed	购买后保修追加销售已完成

顾客事件

事件	说明
customer.policy_assigned	保单已分配给顾客
customer.claim_filed	顾客提交了索赔

---

负载格式

所有负载均采用以下结构：

{
  "id": "wh_evt_abc123def456",
  "event": "policy.created",
  "timestamp": "2026-03-17T14:30:00.000Z",
  "version": "1.0",
  "data": { ... },
  "metadata": {
    "orgId": "org_abc",
    "integrationPlatform": "shopify",
    "shopDomain": "my-store.myshopify.com"
  }
}

• id — 唯一事件 ID（用于去重）
• event — 事件类型
• data — 特定于事件的负载，包含资源详情
• metadata — 组织和集成上下文

---

签名验证

所有 Webhook 都包含 X-Umbrella-Signature 请求头（请求体的 HMAC-SHA256）。处理前请务必验证签名。验证代码示例请参阅 Webhook 参考。

---

重试策略

投递失败（非 2xx 响应或超时）时会按指数退避进行重试：

尝试	延迟
第 1 次重试	30 秒
第 2 次重试	2 分钟
第 3 次重试	10 分钟
第 4 次重试	1 小时
第 5 次重试	6 小时
最后一次重试	24 小时

您的端点必须在 30 秒内返回 200、201 或 202。请立即响应并异步处理，以免超时。

---

设置端点

1. 前往仪表板 → 设置 → Webhook
2. 点击添加端点
3. 输入您的 HTTPS 端点 URL 并选择事件
4. 复制并妥善保存签名密钥（仅显示一次）
5. 在端点详情页面使用发送测试事件进行测试

---

Webhook 日志

日志页面按端点显示投递历史：事件类型、状态（成功/失败/已重试）、响应代码、响应时间、时间戳和尝试次数。

---

相关内容

• Shopify 产品同步 — Shopify Webhook 同步
• Shopify 集成 — Shopify 连接总览
• 小组件配置 — 小组件显示设置