如何通过 Webhook 接收客户的 WhatsApp 消息和社交媒体评论
每个连接都通过 easyCoexistence 的 Partner API 获得自己的 Webhook,用于接收客户的 WhatsApp 消息或社交媒体评论。WhatsApp 消息由 Meta 直接发送到该 URL,签名使用 Tech Provider 应用的密钥,而非您持有的密钥,因此 URL 路径中一段足够长的随机密钥即可完成验证。Instagram 和 Facebook 的评论与私信,以及 TikTok 评论,会在到达时即被转发,并按账户使用 X-EC-Signature 签名。
Meta 规定的备用回调 URL 最大长度,该 URL 用于将号码的消息发送至您的端点。
Meta 重试您的端点未接受的 WhatsApp Webhook 的时长,重试频率逐渐降低,可能产生重复投递。
Meta 的网络;通过 whois 路由查询可列出 WhatsApp Webhook 的来源地址,这些地址由 Meta 定期更改。
Meta 规定的单个 WhatsApp Webhook 负载最大大小。
转发事件的签名时间戳超过此时长即应拒绝;HMAC 应以恒定时间方式比较。
每个连接如何获得自己的接收地址?
每项资源各调用一次接口。WhatsApp 号码使用 PUT /connections/{id}/webhook,并附带 url 和 verify_token;或在其连接会话中使用 webhook_url 和 webhook_verify_token 这一组参数,使号码从接入的第一分钟起即可将消息路由到您。社交账户在连接成功后使用 PUT /channels/{id}/webhook 并附带 url。任一接口中的 url 设为 null 即可关闭投递。两条路径在于由谁投递以及您如何验证身份:
| WhatsApp number | Instagram, Facebook, TikTok | |
|---|---|---|
| Set with | webhook_url on the session, or PUT /connections/{id}/webhook | PUT /channels/{id}/webhook, after it connects |
| Delivered by | Meta, straight to your URL | easyCoexistence, forwarding each event as it arrives |
| Body | Meta's webhook, unchanged | platform, account_id, external_id and the network's entry |
| Authenticate | A long random secret in the URL path | X-EC-Signature, keyed with the account's secret |
| Retries | Meta's own, for up to 7 days | None: one attempt |
| Copy kept | None | None |
如何将号码的消息指向您的端点?
为其提供一个 HTTPS URL,路径中包含一段足够长的随机密钥,并附带验证令牌:连接会话中为 webhook_verify_token,长度 8 至 200 个字符;PUT 中为 verify_token。Meta 会立即使用携带 hub.mode=subscribe、hub.verify_token 和 hub.challenge 的 GET 请求检查该 URL,令牌匹配时,您的端点必须返回 hub.challenge 的值。若此握手失败,PUT 将返回 502 meta_rejected 及 Meta 自身的消息;在连接会话中,号码仍会连接成功,会话的 last_error 会说明 URL 未被应用的原因。
import express from "express";
import { timingSafeEqual } from "node:crypto";
const PATH_SECRET = process.env.WA_PATH_SECRET; // the random part of webhook_url
const VERIFY_TOKEN = process.env.WA_VERIFY_TOKEN; // the verify token you sent
const app = express();
function same(a, b) {
const x = Buffer.from(String(a)), y = Buffer.from(String(b));
return x.length === y.length && timingSafeEqual(x, y);
}
// Meta's handshake, run when the destination is set
app.get("/wa/:secret", (req, res) => {
if (!same(req.params.secret, PATH_SECRET)) return res.sendStatus(404);
if (req.query["hub.mode"] !== "subscribe" || !same(req.query["hub.verify_token"], VERIFY_TOKEN)) {
return res.sendStatus(403);
}
res.send(req.query["hub.challenge"]);
});
// Messages, echoes and the one-time import; payloads reach 3 MB
app.post("/wa/:secret", express.json({ limit: "4mb" }), (req, res) => {
if (!same(req.params.secret, PATH_SECRET)) return res.sendStatus(404);
res.sendStatus(200); // answer first: Meta retries for up to 7 days
enqueue(req.body); // deduplicate on each message id before acting
});为何无法验证 Meta 的签名,取而代之的是什么?
Meta 使用接收应用的 App Secret 对每次投递的负载计算 HMAC-SHA256,结果放在 X-Hub-Signature-256 标头中。对于您客户的号码,该应用是 easyCoexistence 的 Tech Provider 应用,其密钥从不共享,因此您一侧无法验证此标头。取而代之的凭据是 URL 路径中那段足够长的随机密钥:以恒定时间比较,拒绝其他一切请求。作为第二层防护,请将注册给 Meta AS32934 的路由列入允许名单,并定期刷新该名单,因为 Meta 会定期更改其 IP 地址。
哪些 WhatsApp Webhook 会到达您的 URL?
Meta 允许备用回调 URL 携带的字段包括:messages,用于客户发来的消息以及您所发消息的状态;smb_message_echoes,用于商家从 WhatsApp Business 应用发出的消息;以及一次性导入的 history 和 smb_app_state_sync。Meta 从不向备用回调 URL 发送模板 Webhook,也不会发送 account_update 等账户 Webhook,这些会改为发送到 easyCoexistence 的回调地址。因此,模板审核需通过轮询读取,若模板被驳回,则会以状态事件的形式通知您。
- 目的地设置在 WhatsApp Business 账户上,因此同一账户下的两个号码共享该设置:请根据 value.metadata.
phone_number_id进行路由。 - 媒体以 ID 形式到达;请使用凭据接口返回的客户访问令牌,向 Meta 获取文件。
- 负载最大可达 3 MB,因此请调高低于此值的任何请求体大小限制。
转发的社交事件是什么样的?
这是一个 POST 请求,Content-Type 为 application/json,并带有 X-EC-Signature 标头,包含四个键:platform;account_id,即 Partner API 使用的渠道 ID;external_id,即该账户在网络上的 ID;以及 entry。对于 Instagram 和 Facebook,entry 保持为 Meta 的 Webhook entry 原样,其中评论和提及位于 changes 中,私信位于 messaging 中。对于 TikTok,它包含经过解析内容的 comment.update 事件,以及以字符串形式表示的 comment_id、video_id 和 parent_comment_id,因此 64 位 ID 不会被四舍五入。
- Instagram 账户订阅评论、消息和提及;Facebook 专页订阅 feed、messages 和 mention;TikTok 发送 comment.update。
- easyCoexistence 不接收来自 YouTube 或 LinkedIn 的评论事件:对其 PUT 请求会返回 400
not_supported,其评论需使用您的凭据通过各网络的 API 读取。 - 转发请求不带 X-EC-Event 或 X-EC-Delivery 标头,因此请根据网络本身的 ID 去重,例如评论 ID 或消息的 mid。
{
"platform": "instagram",
"account_id": "<CHANNEL_ID>",
"external_id": "<INSTAGRAM_ACCOUNT_ID>",
"entry": {
"id": "<INSTAGRAM_ACCOUNT_ID>",
"time": 1793440800,
"changes": [
{
"field": "comments",
"value": {
"id": "<COMMENT_ID>",
"from": { "id": "<INSTAGRAM_SCOPED_ID>", "username": "<USERNAME>" },
"text": "<COMMENT_TEXT>",
"media": { "id": "<MEDIA_ID>", "media_product_type": "<MEDIA_PRODUCT_TYPE>" }
}
}
]
}
}如何逐步验证 X-EC-Signature?
使用 PUT /channels/{id}/webhook 返回的 signing_secret。该密钥仅显示一次,且对每个账户唯一。标头格式为 t=<unix>,v1=<hex>。然后,对每次投递执行以下步骤:
- 在解析 JSON 之前,以字节形式读取原始请求体。
- 按逗号拆分标头,得到 t(以秒计的 Unix 时间)和 v1(十六进制摘要)。
- 若 t 与您的时钟相差超过 5 分钟,则拒绝该次投递。
- 以该账户的密钥,对 t、点(.)和原始请求体计算 HMAC-SHA256,结果以十六进制表示。
- 使用恒定时间方式与 v1 比较,然后返回 2xx 并将任务排入队列。
import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";
const app = express();
const secrets = new Map(); // channel id -> signing_secret, kept in your database
app.post("/hooks/social", express.raw({ type: "application/json" }), (req, res) => {
const sig = Object.fromEntries(
(req.get("X-EC-Signature") ?? "").split(",").map((part) => part.split("=", 2)),
);
if (!/^\d+$/.test(sig.t ?? "") || Math.abs(Date.now() / 1000 - Number(sig.t)) > 300) {
return res.sendStatus(401); // missing or stale timestamp
}
let event;
try {
event = JSON.parse(req.body.toString("utf8")); // platform, account_id, external_id, entry
} catch {
return res.sendStatus(400);
}
const secret = secrets.get(event.account_id);
if (!secret || !sig.v1) return res.sendStatus(401);
const expected = createHmac("sha256", secret)
.update(sig.t + ".")
.update(req.body) // the raw bytes, exactly as they arrived
.digest("hex");
if (expected.length !== sig.v1.length ||
!timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1))) {
return res.sendStatus(401);
}
res.sendStatus(204); // one attempt and no retries: acknowledge, then work
enqueue(event);
});未设置接收地址时会发生什么?
您将收不到任何消息,也不会有待发送的内容被保留。未设置 webhook_url 的号码会回退到 easyCoexistence 的回调地址,其消息会被丢弃且不予保存,并且不会导入聊天记录,因为聊天记录只有在接收地址存在后才会请求导入。未设置接收地址的社交账户不会被转发:其事件仍会到达 easyCoexistence 的应用,但不会为您保留任何事件。请在需要流量之前设置好各个接收地址。
连接断开或被移除时,接收地址会怎样?
号码的接收地址会保留在记录中。当断开的号码重新连接时,easyCoexistence 会再次向 Meta 设置您的 URL;暂停的号码恢复后也会如此。移除社交账户会清除其接收地址和密钥,因此在其重新连接后,请再次调用 PUT /channels/{id}/webhook 并保存新密钥。只要带 URL 调用该 PUT,就会签发新密钥,而旧密钥会立即停止签名。
设置方法
- Put a secret in the URLChoose an HTTPS URL whose path holds a long random string, 200 characters or fewer in all, and make its GET answer Meta's hub.challenge.
- Route the number's messagesSend webhook_url and webhook_verify_token on the connect session, or PUT /connections/{id}/webhook once the number is connected.
- Turn on each social accountCall PUT /channels/{id}/webhook with your URL and store the signing_secret it returns against that channel.
- Verify, then acknowledgeCheck the path secret on WhatsApp deliveries and X-EC-Signature on forwarded ones, answer 2xx at once, then process from a queue.
常见错误
- 不要对您客户的 WhatsApp 投递检查 X-Hub-Signature-256。Meta 使用 easyCoexistence 的应用密钥计算该值,而该密钥从不共享,因此检查无法通过;请改用 URL 路径中的密钥进行验证。
- 不要基于解析后的 JSON 验证 X-EC-Signature。HMAC 按原始请求体的字节逐一计算,重新序列化会改变字节,因此应先验证,再解析。
- 不要为所有渠道使用同一个密钥。每个社交账户使用各自的密钥签名,状态事件则使用另一把密钥,因此请根据 account_id 查找对应密钥。
- 不要在响应转发事件之前执行耗时操作。该事件只发送一次,会等待您的响应 8 秒,且从不重试,因此请先返回 2xx,之后再处理。
easyCoexistence 直接将每个客户号码的消息从 Meta 路由到您的服务器;Instagram 和 Facebook 的评论与私信,以及 TikTok 评论,会在到达时按账户签名转发至您的端点,不保留副本,所有连接全天候监控。每个连接每月 US$ 9 起,连接越多单价越低,最低降至 US$ 0.75,并提供前 3 天免费试用。
常见问题
我能否验证 Meta 对客户 WhatsApp 消息的签名?
不能。Meta 使用 easyCoexistence 的 Tech Provider 应用密钥签名,该密钥从不共享。请使用 URL 路径中足够长的随机密钥进行验证,也可选择使用 Meta 的 IP 范围。
YouTube 和 LinkedIn 连接会转发评论事件吗?
不会。easyCoexistence 不接收这两者的评论事件,因此 PUT /channels/{id}/webhook 会返回 400 not_supported。请使用该渠道的凭据,通过各网络的 API 读取其评论。
如果我的服务器宕机,转发的社交事件会重试吗?
不会。每个事件只发送一次,且不保留副本。WhatsApp 投递有所不同,因为 Meta 本身会将其重试长达 7 天。
消息会经过 easyCoexistence 吗?
WhatsApp 不会:Meta 直接将号码的消息投递到您设置的 Webhook。社交网络的评论和私信会在到达时被转发至您的端点,按账户签名,且不保留副本。
继续阅读
两分钟连接您的第一个渠道。
无需等待平台审核。连接 WhatsApp、Instagram、TikTok 或其他渠道,然后让您的 AI 发布、回复或生成报告,看它如何运作。
- 免费试用 3 天
- 随时取消
- 仅使用官方 API
- 全天候 24/7 监控
验证时间