WhatsApp Webhook指南：事件、安全与重试

{
  "messageId": "2603121407537573731",
  "channel": "SMS",
  "destination": "447700900123",
  "status": "DELIVERED",
  "timestamp": "2026-10-10T09:15:42Z",
  "reason": null
}

如何编写可靠的处理程序？

按顺序做三件事：保存原始事件，以2xx确认，然后异步处理。下面的处理程序遵循我们文档中的模式。

import express from "express";

const app = express();

// 捕获原始请求体，以便按收到的原样存储。
app.post(
  "/webhooks/omnichannels",
  express.json({ verify: (req, _res, buf) => { req.rawBody = buf.toString("utf8"); } }),
  async (req, res) => {
    try {
      await db.webhookEvents.insert({ receivedAt: new Date(), body: req.rawBody });
    } catch (err) {
      return res.sendStatus(500); // 存储失败：让事件被重试
    }
    res.sendStatus(200);          // 尽快确认
    queue.publish("status-events", req.body); // 把真正的工作放到别处
  },
);

// 工作进程：幂等处理
async function processEvent(event) {
  const id = event.messageId ?? event.message_id ?? event.id; // 按渠道映射
  const status = event.status;
  const rank = { SUBMITTED: 1, SENT: 2, DELIVERED: 3, READ: 4, FAILED: 4, REJECTED: 4 };

  const current = await db.messages.findOne({ providerId: id });
  if (!current) return; // 未知消息：记录日志并调查
  if ((rank[status] ?? 0) <= (rank[current.status] ?? 0)) return; // 重复或过时

  await db.messages.update({ providerId: id }, { status, updatedAt: new Date() });
}

from datetime import datetime, timezone
from flask import Flask, request

app = Flask(__name__)

RANK = {"SUBMITTED": 1, "SENT": 2, "DELIVERED": 3, "READ": 4, "FAILED": 4, "REJECTED": 4}


@app.post("/webhooks/omnichannels")
def omnichannels_webhook():
    raw = request.get_data(as_text=True)
    try:
        db.webhook_events.insert({"received_at": datetime.now(timezone.utc), "body": raw})
    except Exception:
        return "", 500           # 存储失败：让事件被重试
    queue.publish("status-events", raw)  # 异步处理
    return "", 200               # 尽快确认

db和queue对象是您自己的存储和任务队列。rank映射使处理具备幂等性：重复或过时的事件不是推进，因此会被忽略。

可靠处理程序的规则

• **在几秒钟之内响应。**响应之前不要做繁重的工作。
• **只有在事件已保存之后才返回2xx。**如果存储失败，请返回5xx。
• **按消息ID去重。**同一状态可能多次到达。
• **绝不要在处理程序中重发消息。**请在检查状态之后，于单独的任务中决定重试。
• **保留原始请求体，**用于排查问题，以及在修复后重放事件。

如何保护WhatsApp Webhook的安全？

这取决于谁向您的端点发送。Meta会为发送到您在Meta注册的应用的Webhook签名。OmniChannels.ai的API规范没有定义Webhook签名请求头，所以不要等待它。

对于Meta的方案，Meta的文档说明，应使用您的应用密钥对JSON负载生成HMAC-SHA256哈希，并与X-Hub-Signature-256请求头中sha256=之后的值比对。HMAC本身由RFC 2104定义。请对原始字节计算，而不是对重新序列化的对象计算，并以恒定时间比较。

对于我们的端点：

• 仅使用HTTPS，并配有效证书。
• 使用较长且不可猜测的路径，泄露时请轮换。
• 校验请求体的结构，拒绝任何意外内容。
• 把事件视为通知。在执行退款或欺诈锁定等不可逆操作之前，请通过轮询调用确认状态。

投递失败时会怎样？

重试取决于发送方。Meta的文档称，它会以递减的频率重试失败的投递，最长7天，这可能产生重复通知。这是即使您很少看到重复，也应具备幂等性的理由。对于来自我们平台的事件，请与您的开通工程师确认重试行为，而不要假定它与Meta相同。

无论哪种情况，既要防重复，也要防丢失：您的端点可能在部署期间宕机，防火墙规则也可能悄悄丢弃请求。

如何恢复丢失的事件？

轮询批次，而不是重发消息。

curl "https://api.broadnet.me/whatsapp/message/bulk-insights?batch_Id=2609091405000000001&page=0&size=100" \
  -H "Authorization: Bearer $BROADNET_TOKEN"

batch_Id是发送调用返回的ID，page从零开始。请运行一个夜间对账任务，读取前一天的批次并填补任何缺口。

故障排查清单

1. URL是否配置在了正确的账户或子账户上？
2. 端点能否通过带有效证书的HTTPS访问？
3. 它是否迅速返回2xx，还是超时？
4. 是否有防火墙或WAF规则在拦截请求？
5. 您是否在解析之前记录了原始请求体，让解析错误无法掩盖事件？

实战示例：一家零售商的通知管道

“Souq Rafiq”（虚构）是阿联酋的一家零售商，通过WhatsApp发送订单更新，并希望在订单工具中获得准确的状态。

1. 订单通过sendbulk发送，batchId存储在订单上。请参阅通过API发送WhatsApp消息。
2. Webhook端点把每个事件写入一张表，然后返回200。
3. 工作进程为状态排序，并更新订单的消息状态。
4. FAILED事件会为客服创建一个带原因的任务，并按渠道回退考虑短信回退。
5. 收到的客户消息被转到共享收件箱，让客服可以在窗口内回复。
6. 夜间任务对昨天的批次调用bulk-insights，并纠正任何遗漏。

常见错误有哪些？

• **响应之前做繁重的工作，**导致超时和重复投递。
• **先确认再存储，**导致存储失败时事件丢失。
• **相信顺序。**迟到的SENT覆盖了DELIVERED。
• **依据示意性负载编写代码，**而不是依据真实事件。
• **检查签名之前重新序列化JSON，**会改变字节。
• **在处理程序中重发，**可能造成循环。
• **局限：**本指南描述的是我们文档中记载的行为。您账户的重试策略和负载字段，应在开通期间确认。

OmniChannels.ai 如何提供帮助

OmniChannels.ai把WhatsApp、短信、RCS和其他渠道的送达状态和收到的消息，以一种统一的格式推送到您的Webhook，并为转售商提供按子账户划分的单独Webhook。BroadNet是Meta官方的Business Solution Provider，因此Meta自身的Webhook要求已为您处理，您只需使用我们的API。请阅读Webhook参考和WhatsApp API文档，或查看事件在共享收件箱中的呈现方式。