登录开始免费试用
easyCoexistence 官方 API

Facebook Webhook 验证:hub.challenge 与 X-Hub-Signature-256

Facebook 通过一个 GET 请求验证 Webhook 端点,该请求携带值为 subscribe 的 hub.mode、hub.verify_token 和 hub.challenge。端点会将令牌与应用控制台中的令牌比对,并将 challenge 作为响应正文返回。之后每个事件都以 POST 形式到达,并在 X-Hub-Signature-256 中签名:sha256= 后接以 App Secret 为密钥、对负载计算的 HMAC-SHA256。

easyCoexistence 为您连接的每个主页处理 Meta 一侧的工作:其应用响应 hub.challenge,校验 X-Hub-Signature-256,并为主页订阅 `feed`、`messages` 和 `mention`,然后将事件以 X-EC-Signature 签名并使用该主页专属密钥,转发到您的 HTTPS 端点。

subscribe

Meta 验证请求中 hub.mode 始终携带的值;hub.challenge 为需要原样返回的整数。

sha256=

X-Hub-Signature-256 的前缀,后接 Meta 根据负载和 App Secret 生成的 SHA256 签名。

5 seconds

Messenger Webhook 端点应多快以 200 OK 响应每条通知。

1 hour

触发 Webhooks Disabled 警报并取消应用主页订阅前的失败投递次数。

36 hours

Meta 在丢弃失败的主页通知前,以递减的频率重试多长时间。

Meta 的验证请求包含什么?

在应用控制台中配置 Webhooks 产品,或通过 /{app-id}/subscriptions 创建订阅时,Meta 会向 callback URL 发送一个 GET 请求。该请求附带三个查询参数:

  • hub.mode:始终为 subscribe。
  • hub.challenge:端点必须回传的整数。
  • hub.verify_token:在控制台 Verify Token 字段中输入的字符串。
  • PHP 会把点号转换为下划线,因此会读取为 hub_mode、hub_challenge 和 hub_verify_token。

端点应如何响应?

仅当 hub.mode 为 subscribe 且 hub.verify_token 匹配时,端点才返回 200,响应正文即为 hub.challenge 的值;其他情况返回 403,与 Meta 的示例应用一致。控制台会显示端点是否通过验证,/{app-id}/subscriptions 则返回成功或错误。端点必须使用 HTTPS,并配有有效的 TLS 或 SSL 证书,因为不支持自签名证书。

X-Hub-Signature-256 如何计算?

它是对请求负载计算的 HMAC-SHA256,以应用的 App Secret 为密钥,结果以小写十六进制表示,并以 sha256= 为前缀。Meta 的 Messenger 指南补充说明,签名计算的是 Unicode 转义后的负载,因此 äöå 这样的字符串按 \u00e4\u00f6\u00e5 计算:必须对接收到的原始正文进行哈希,不能对解码后或重新序列化的副本进行哈希。Meta 表示验证签名是可选的,但强烈建议验证。

如何在代码中进行校验?

保留原始字节,计算 HMAC,以恒定时间比较,然后再解析。Flask 的 get_data 会原样返回正文,这正是签名计算时所用的内容;如果先解析再重新序列化,字节就会改变。以下是一个简单的端点,用于应答验证并校验每个 POST:

Python: hub.challenge and X-Hub-Signature-256
import hashlib, hmac, os
from flask import Flask, abort, request

app = Flask(__name__)
VERIFY_TOKEN = os.environ["VERIFY_TOKEN"]
APP_SECRET = os.environ["APP_SECRET"].encode()

@app.get("/webhooks/facebook")
def verify():
    token = request.args.get("hub.verify_token", "")
    if request.args.get("hub.mode") == "subscribe" and hmac.compare_digest(token.encode(), VERIFY_TOKEN.encode()):
        return request.args.get("hub.challenge", ""), 200
    abort(403)

@app.post("/webhooks/facebook")
def receive():
    raw = request.get_data()  # the bytes Meta signed
    expected = "sha256=" + hmac.new(APP_SECRET, raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected.encode(), request.headers.get("X-Hub-Signature-256", "").encode()):
        abort(401)
    # answer at once; hand request.get_json() to a queue for the work
    return "EVENT_RECEIVED", 200

验证后 Meta 期望什么?

每条通知都应返回 200 OK,Messenger 事件须在 5 秒内返回。Meta 每次投递最多批量包含 1,000 条更新,但不保证该数量,失败处理方式如下:

  • 主页通知:立即重试,之后再以递减的频率重试数次,历时 36 小时,然后丢弃。
  • Messenger 通知:立即重试数次;失败持续 15 分钟后,警报会发送到开发者账户。
  • 失败持续 1 小时后,会发出 Webhooks Disabled 警报,应用将被取消对主页的订阅,直至重新订阅。
  • 重试可能导致事件被投递两次且顺序错乱,因此需要去重,并按时间戳对 `messages` 排序。
  • 之前的通知之后无法查询,因此应在接收时保存所需内容。

easyCoexistence 如何通过 Meta 的检查?

其 Meta 应用为所连接的主页设置了一个 callback URL,该端点自行完成两项检查。仅当 hub.mode 为 subscribe 且 hub.verify_token 匹配(以恒定时间比较)时才响应 GET,否则返回 403;它将每个 POST 作为原始文本读取,使用其 App Secret 重新计算 X-Hub-Signature-256,不一致时以 401 拒绝,并立即应答 Meta,在响应之后再处理事件。

easyCoexistence 如何为转发内容签名?

它使用自有签名,因为 Meta 的标头只能用 easyCoexistence 的 App Secret 校验,且不会被转发。对于已连接且已设置端点的每个主页条目,都会以 JSON 形式 POST 到该端点,内容为 {platform, account_id, external_id, entry},并附带 X-EC-Signature 标头,格式为 t=<unix>,v1=<hex>。其中 v1 是时间戳、一个点(.)和原始正文的 HMAC-SHA256,以该主页的签名密钥为密钥:

  • 密钥以 whsec_ 开头,仅显示一次,可通过 Partner API 的 set_social_webhook_destination 或 PUT /channels/:id/webhook 设置。
  • 重新设置 URL 会签发新密钥;将 URL 设为 null 则关闭转发。
  • 每次转发仅发送一次,最长等待 8 秒,不跟随重定向,且只发送到解析为公网 IP 的 HTTPS 地址。
  • 事件副本不会保存,因此无法重试。

如何校验 X-EC-Signature?

将标头拆分为 t 和 v1,拒绝超过 5 分钟的时间戳,使用该主页的签名密钥重新计算 t、一个点(.)和原始正文的 HMAC,并以恒定时间比较。以下为以原始字节保存正文的 Node.js 示例:

Node.js: checking X-EC-Signature on a forwarded event
import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.EC_SIGNING_SECRET; // whsec_..., shown once

app.post("/events/facebook", express.raw({ type: "application/json" }), (req, res) => {
  const sig = Object.fromEntries(
    String(req.get("X-EC-Signature") ?? "").split(",").map((part) => part.split("="))
  );
  const fresh = Math.abs(Date.now() / 1000 - Number(sig.t)) <= 300;
  const expected = crypto
    .createHmac("sha256", SECRET)
    .update(Buffer.concat([Buffer.from(`${sig.t}.`), req.body]))
    .digest("hex");
  const ok = fresh && typeof sig.v1 === "string" && sig.v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1));
  if (!ok) return res.sendStatus(401);
  res.sendStatus(200); // answer first: forwards are not retried
  const { platform, account_id, external_id, entry } = JSON.parse(req.body.toString("utf8"));
  // queue entry for the work
});

常见错误

  • 把 hub.challenge 包裹在 JSON 或引号中。200 响应的正文必须是 challenge 值本身。
  • 在 JSON 解析器之后计算 HMAC。解析并重新序列化会改变字节,而 Meta 对 Unicode 转义后的负载签名,因此应对原始正文进行哈希。
  • 先处理再应答。Messenger 要求 5 秒内返回 200,连续失败一小时会取消应用对主页的订阅。
  • 对转发事件校验 Meta 的签名。Meta 使用 easyCoexistence 的 App Secret 签名;转发事件携带 X-EC-Signature,应使用该主页的签名密钥校验。
使用 EasyCoexistence 完成这些操作

每个连接每月 US$ 9 起,最低降至 US$ 0.75,连接越多单价越低,前 3 天免费试用。

常见问题

验证令牌从哪里来?

由您自行选择。它是在应用控制台配置 Webhook 时,在 Verify Token 字段中输入的字符串,或发送给 /{app-id}/subscriptions 的 verify_token。

可以用 curl 测试验证吗?

可以。Meta 的 Messenger 指南会发送一个 GET 请求,其中包含 hub.verify_token、hub.challenge=CHALLENGE_ACCEPTED 和 hub.mode=subscribe;正常工作的端点会返回 CHALLENGE_ACCEPTED。

如果端点故障持续一小时会怎样?

Meta 会发出 Webhooks Disabled 警报,并取消应用对主页的订阅。修复端点后,请通过 subscribed_apps 重新订阅该主页。

接收主页的 Webhook 是否需要自己的 Meta 应用?

使用 easyCoexistence 时不需要。Meta 将事件投递到其应用,再由该应用把每个主页的事件转发到您设置的端点,并使用 X-EC-Signature 签名。

继续阅读

两分钟连接您的第一个渠道。

无需等待平台审核。连接 WhatsApp、Instagram、TikTok 或其他渠道,然后让您的 AI 发布、回复或生成报告,看它如何运作。

  • 免费试用 3 天
  • 随时取消
  • 仅使用官方 API
  • 全天候 24/7 监控

验证时间