2. Webhook 工作流程：事件源、HTTP回调、负载格式、接收端处理逻辑

Webhook 的本质是一种“反向 API”：由事件源主动向预先注册的接收端 URL 发起 HTTP 请求，携带事件数据。理解其完整工作流程，是后续调度策略调优的基础。本章将拆解流程中的四个核心环节：事件源、HTTP 回调、负载格式、接收端处理逻辑。

2.1 整体流程概览

下图展示了 Webhook 从事件产生到接收端消费的完整链路，包含重试与签名验证等关键节点。

2.2 事件源：Webhook 的触发器

事件源是 Webhook 的起点。任何能够产生状态变化并对外发送通知的系统，都可以作为事件源。常见的事件源类型包括：

2.3 HTTP 回调：传输协议与行为约定

事件源通过 HTTP POST 请求将事件数据发送到接收端。回调的可靠性、安全性和性能直接决定了 Webhook 系统的质量。

2.3.1 请求结构

POST /webhooks/receiver HTTP/1.1
Host: api.example.com
Content-Type: application/json
User-Agent: Webhook-Source/1.0
X-Webhook-ID: evt_abc123
X-Webhook-Signature: sha256=abc123def456...
X-Webhook-Timestamp: 1710000000

{
  "event": "order.paid",
  "id": "ord_789",
  "data": {
    "amount": 2999,
    "currency": "USD",
    "customer_email": "user@example.com"
  }
}

2.3.2 关键 HTTP 行为约定

2.4 负载格式：事件数据的载体

Webhook 负载通常采用 JSON 格式，但不同事件源的结构差异很大。接收端需要能够解析多种负载结构，并从中提取关键字段。

2.4.1 常见负载结构对比

2.4.2 负载格式调优建议

• 最小化原则： 只发送接收端必需的字段，减少网络传输开销。
• 版本化： 在负载中包含 version 字段，便于接收端做向后兼容。
• 避免深层嵌套： 超过 3 层的嵌套会增加解析复杂度和出错概率。
• 统一时间格式： 所有时间字段使用 ISO 8601 格式（如 2025-01-15T10:30:00Z）。

2.5 接收端处理逻辑：从验证到响应

接收端是 Webhook 流程的终点，也是调度策略调优的最终落脚点。一个健壮的接收端处理逻辑应包含以下步骤：

1. 签名验证 — 使用预共享密钥对请求体计算 HMAC，与 X-Webhook-Signature 比对。
2. 幂等性检查 — 根据 X-Webhook-ID 或事件 ID 查询去重缓存（如 Redis），已处理则直接返回 200。
3. 负载解析与校验 — 解析 JSON，校验必填字段、事件类型、数据格式。
4. 业务处理 — 根据事件类型执行对应的业务逻辑（如更新订单状态、发送通知）。
5. 异步化 — 将耗时操作（如调用第三方 API、发送邮件）放入消息队列，快速返回 200。
6. 响应 — 返回 HTTP 200 OK，可选返回处理结果摘要。

2.6 接收端处理逻辑代码示例

以下是一个基于 Node.js (Express) 的接收端核心处理逻辑片段，展示了签名验证、幂等检查和异步化处理：

const express = require('express');
const crypto = require('crypto');
const { processOrderPaid } = require('./handlers');
const { idempotencyCheck } = require('./cache');

const app = express();
app.use(express.json({ verify: (req, res, buf) => { req.rawBody = buf; } }));

const SECRET = process.env.WEBHOOK_SECRET;

function verifySignature(req) {
  const signature = req.headers['x-webhook-signature'];
  const timestamp = req.headers['x-webhook-timestamp'];
  const payload = req.rawBody.toString();
  const expected = crypto
    .createHmac('sha256', SECRET)
    .update(`${timestamp}.${payload}`)
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(`sha256=${expected}`));
}

app.post('/webhooks/receiver', async (req, res) => {
  // 1. 签名验证
  if (!verifySignature(req)) {
    return res.status(401).json({ error: 'invalid signature' });
  }

  const eventId = req.headers['x-webhook-id'] || req.body.id;

  // 2. 幂等性检查
  const alreadyProcessed = await idempotencyCheck(eventId);
  if (alreadyProcessed) {
    return res.status(200).json({ status: 'duplicate' });
  }

  // 3. 负载解析与校验
  const { event, data } = req.body;
  if (!event || !data) {
    return res.status(400).json({ error: 'invalid payload' });
  }

  // 4. 异步化处理（放入消息队列）
  setImmediate(() => {
    processOrderPaid(event, data).catch(err => {
      console.error('Handler error:', err);
    });
  });

  // 5. 快速返回 200
  res.status(200).json({ status: 'accepted' });
});

app.listen(3000);