Webhook 事件桥接规则

适用于第三方系统回调、事件同步、状态回传的签名校验与可靠投递场景。

规则文件内容

请复制以下内容，保存为 .cursor/rules/webhook-event-bridge.mdc：

---
description: Webhook 签名校验、事件去重、重放保护与死信处理规则
globs: src/integrations/webhook/**, src/modules/events/**
---

# Webhook 事件桥接业务规则

## 1. 核心原则
- **先验签后处理**：未通过签名校验的事件一律拒绝。
- **至少一次投递**：接收端要具备去重与补偿能力。
- **失败可追踪**：失败事件需进入重试队列或死信队列。

## 2. 验签规则
- 必须校验 `timestamp + nonce + payload` 的 HMAC 签名。
- 请求时间漂移超过 `5` 分钟拒绝处理。
- 验签失败返回 `401`，记录来源 IP 与签名摘要。

## 3. 事件幂等规则
- 使用 `event_id` 做唯一去重。
- 同一 `event_id` 重复到达直接 ACK 并跳过业务处理。
- `event_id` 相同但 `payload_hash` 不同，标记为冲突事件。

```ts
interface WebhookEvent {
  eventId: string;
  eventType: string;
  source: string;
  occurredAt: string;
  payloadHash: string;
}

4. 路由与顺序规则

• 按 event_type 路由到对应处理器。
• 同一业务对象事件需按 occurred_at 顺序消费。
• 无处理器的事件进入 unknown_event 队列待人工处理。

5. 重试与死信规则

• 可重试错误：网络超时、下游 5xx、临时锁冲突。
• 重试上限 5 次，退避策略：1m/5m/15m/30m/60m。
• 达到上限后进入死信队列并触发告警。

6. 回执规则

• 业务接收成功返回 200 + ack_id。
• 异步处理场景可先返回 202，后续通过状态接口查询。
• 返回体禁止暴露内部堆栈信息。

7. 可观测规则

• 必须记录：event_id, event_type, source, status, latency_ms。
• 关键指标：成功率、延迟分位、重试率、死信数。
• 单来源失败率突增需自动告警。

8. 数据模型约束

• webhook_events 必须包含：event_id, event_type, source, payload_hash, status, received_at
• webhook_retry_tasks 必须包含：event_id, retry_count, next_retry_at, last_error_code
• webhook_dead_letters 必须包含：event_id, reason, payload_snapshot, created_at

9. 实施注意事项

• 验签密钥必须支持轮换与双密钥灰度。
• 回调来源 IP 白名单建议与签名校验双重启用。
• 大 payload 建议压缩并设置体积上限。

## 适用场景

- 第三方平台事件回调
- 系统间状态同步
- 异步消息桥接处理