Webhook 回调服务搭建

解决什么问题

事件驱动集成的难点不在“收到回调”，而在回调在真实网络环境下会出什么错。供应商在未收到及时的 200 OK 时会重试，你的处理函数因此可能被调用多次；延迟、乱序、重放攻击和部署期间的服务中断都是常见故障模式。手工拼装可靠接收端，意味着自己处理签名验证、幂等键存储、异步队列和死信策略，很容易遗漏某一项。

核心能力与关键步骤

• 设计回调端点：在稳定且不可猜测的路径上创建 HTTP POST 端点（如 /webhooks/stripe），仅使用 HTTPS，快速返回 200 OK，重处理交给作业队列。
• 签名验证：处理任何事件前用供应商签名密钥校验 HMAC-SHA256、RSA 等签名，用常数时间比较防止时序攻击；缺失或无效签名直接返回 401 Unauthorized；始终读取原始请求体验证，解析后的 JSON 可能与签名字节不一致。
• 事件解析与路由：按事件类型（如 payment_intent.succeeded）路由到专用处理函数，未识别的类型记为 warning 并仍返回 200 OK，避免供应商无限重试。
• 幂等处理：将已处理的事件 ID 存入数据库，处理前查重，用数据库事务原子地标记已处理并执行副作用。
• 异步处理与死信队列：耗时操作先确认再入队后台处理；耗尽重试的失败事件移入死信队列供人工排查，并对队列深度设置监控告警。
• 供应商侧配置：注册端点 URL，只订阅需要的事件类型，保存签名密钥，用供应商测试功能验证。

适用边界与注意点

支持 Express.js、Fastify、Flask、FastAPI、Django、Rails、Spring Boot 等框架，配合 BullMQ、Celery、Sidekiq、SQS、RabbitMQ 队列和 PostgreSQL、MySQL、Redis 做幂等跟踪。

需要注意：乱序投递是常态，应按事件时间戳和资源当前状态做决策而非假设顺序；轮换签名密钥期间新旧密钥都要支持；更换端点 URL 时先注册新地址再注销旧地址；部分供应商的 push 事件 payload 很大，要设置合理的 body 限制并优雅处理 413。