Instagram Webhook 验证:hub.challenge 与 X-Hub-Signature-256
设置 Instagram Webhook 需要一个 HTTPS 端点,用于应答 Meta 的验证 GET 请求。该请求携带值为 subscribe 的 hub.mode、hub.verify_token 和 hub.challenge。端点核对令牌后,返回 hub.challenge 的值。应用订阅字段后,每个账户还需通过 subscribed_apps 边完成订阅,之后 Meta 会以 POST 发送 JSON 事件,这些事件使用应用密钥签名,签名放在 X-Hub-Signature-256 中。
easyCoexistence 负责 Meta 这一侧:其应用通过验证,校验 X-Hub-Signature-256,为每个已连接的 Instagram 账户订阅评论、消息和提及,并以 X-EC-Signature 签名将事件转发到您的 HTTPS 端点。
在 Meta 的验证请求中,hub.mode 始终携带该值。
Meta 重试失败通知的时长,重试频率递减,之后丢弃该通知。
Meta 向开发者账户发出警报前,消息投递失败的次数。
出现 Webhooks Disabled 警报并取消应用对该账户订阅之前,消息投递失败的次数。
应用在接收其用户账户的通知前,须达到 Meta 要求的应用模式。
Instagram Webhook 设置是如何进行的?
按照 Meta 指南给出的顺序,分四步完成。端点必须先通过验证,才能选择任何字段;应用需处于 Live 模式才能接收其用户账户的通知;生产环境访问则需要完成业务验证。
验证请求包含什么?
这是发送到回调 URL 的 GET 请求,每当在应用控制台中配置 Webhooks 产品时都会发出。当 hub.verify_token 与端点自身的令牌一致时,端点返回 200,响应正文仅为 hub.challenge 的值;否则返回 403。应用控制台会显示端点是否通过验证。
- hub.mode:始终为 subscribe。
- hub.challenge:Meta 生成的整数,端点必须将其原样返回。
- hub.
verify_token:在应用控制台的 Verify Token 字段中填写的字符串,只有 Meta 和端点应当知晓。 - 在 PHP 中,这些名称中的点会变成下划线,因此这些值会以
hub_mode、hub_challenge和hub_verify_token的形式到达。
GET https://<YOUR_HOST>/webhooks/instagram
?hub.mode=subscribe
&hub.challenge=1158201444
&hub.verify_token=<YOUR_VERIFY_TOKEN>
HTTP/1.1 200 OK
Content-Type: text/plain
1158201444回调和字段在哪里设置?
在应用控制台中,依次进入 Instagram、「API setup with Instagram login」和「Configure webhooks」:回调 URL 与验证令牌填在这里,保存后会触发验证请求。Instagram 产品默认已订阅 comments、live_comments、message_reactions、messages、messaging_optins、messaging_postbacks、messaging_referral 和 messaging_seen,「Manage」可以取消其中任意一项订阅。「Test」按钮会为所选字段发送一条示例通知。
X-Hub-Signature-256 如何校验?
Meta 使用应用密钥对每条事件通知的负载计算 HMAC-SHA256,结果以 sha256= 加十六进制摘要的形式放在 X-Hub-Signature-256 中。接收方对原始请求正文计算相同的 HMAC,并以恒定时间与请求头比较。Meta 的消息指南指出,签名基于经 Unicode 转义的负载,因此对解码或重新序列化后的 JSON 进行哈希,会得到不同的结果。
import crypto from "node:crypto";
import express from "express";
const app = express();
const { VERIFY_TOKEN, APP_SECRET } = process.env;
// Verification request: send hub.challenge back when the token matches
app.get("/webhooks/instagram", (req, res) => {
const ok = req.query["hub.mode"] === "subscribe" &&
req.query["hub.verify_token"] === VERIFY_TOKEN;
if (!ok) return res.sendStatus(403);
res.status(200).type("text/plain").send(req.query["hub.challenge"]);
});
// Event notification: check the signature over the raw bytes
app.post("/webhooks/instagram", express.raw({ type: "application/json" }), (req, res) => {
const expected = Buffer.from(
"sha256=" + crypto.createHmac("sha256", APP_SECRET).update(req.body).digest("hex")
);
const given = Buffer.from(req.get("X-Hub-Signature-256") ?? "");
if (given.length !== expected.length || !crypto.timingSafeEqual(given, expected)) {
return res.sendStatus(401);
}
res.sendStatus(200); // answer first, work after
const body = JSON.parse(req.body.toString("utf8"));
// hand body.entry to a queue or background job
});
app.listen(3000);为什么只有应用密钥能校验?
因为签名是以该密钥为键的 HMAC。没有它,任何人都无法计算预期值;即使持有某个负载的副本,也无法伪造,因此校验必须在接收应用请求的服务器上进行。Meta 要求应用密钥、访问令牌和客户端凭据不得出现在日志或支持请求中。接收由其他应用转发事件的系统无法校验 Meta 的签名,只能依赖该应用自身的签名。
为什么每个账户都需要单独订阅?
因为应用控制台设定了应用可以接收的内容,而某个账户的通知只有在该账户也完成订阅后才会开始。使用 Instagram Login 时,请向 graph.instagram.com 发送 POST /<IG_ID>/subscribed_apps,附上该账户的 Instagram User 访问令牌,以及 subscribed_fields(应用所选字段,以逗号分隔)。调用成功时,返回 success 为 true。
POST https://graph.instagram.com/<IG_ID>/subscribed_apps
?subscribed_fields=comments,messages
&access_token=<INSTAGRAM_USER_ACCESS_TOKEN>
{ "success": true }投递失败时 Meta 会怎样处理?
Meta 会先重试,之后放弃。Meta 的指南要求对每条通知返回 200 OK,并提醒批量发送(最多 1,000 条更新)不作保证。失败的更新会立即重试,之后在 36 小时内以递减的频率再重试数次,然后丢弃,因此同一事件可能送达两次。消息类事件遵循 Meta 的消息投递规则,处理速度更快:
- 预期在 5 秒内返回 200 OK;投递失败会立即重试数次,因此请按消息 mid 去重。
- 失败持续 15 分钟后,系统会向开发者账户发送警报。
- 失败持续一小时后,会发出 Webhooks Disabled 警报,应用会被取消该账户 Webhooks 的订阅,直到重新订阅为止。
- 故障期间发送的消息可能乱序到达,因此请按时间戳排序。
收不到通知时应检查什么?
以下是 Meta 的故障排查清单,涵盖大多数无响应端点的情况,请按此顺序检查:
- 回调 URL 已通过验证,可通过 HTTPS 访问,并使用有效证书;不支持自签名证书。
- 应用已选择该字段,并拥有所需的访问级别,即 comments 与
live_comments需要 Advanced Access。 - 已通过
subscribed_apps为该账户启用通知,且所用令牌来自同一登录设置。 - 账户符合字段规则:评论通知要求媒体归公开账户所有。
- 服务器应先返回 success,再开始耗时的工作。
为什么 easyCoexistence 要重新签名转发的事件?
因为 Meta 的签名无法随事件一起传递。easyCoexistence 的应用接收 Meta 的投递,使用自身的应用密钥校验 X-Hub-Signature-256,立即向 Meta 应答,并将已连接账户的每个 entry,以 POST 方式发送到该账户设置的端点。正文是新的结构,包含 platform、account_id、external_id 和 entry。Meta 的请求头不会被转发,没有该密钥也无法校验。因此每次转发都带有 Content-Type: application/json 以及 X-EC-Signature,它使用专属于该账户的密钥签名。
如何校验 X-EC-Signature?
请求头格式为 t=<unix>,v1=<hex>,其中 v1 是以该账户的签名密钥为键,对时间戳、点号和原始正文拼接后计算出的十六进制 HMAC-SHA256。请对收到的原始字节重新计算,以恒定时间比较,并拒绝超过 5 分钟的时间戳。
- 密钥以 whsec_ 开头,仅在设置 URL 时由
set_social_webhook_destination或 PUT /channels/:id/webhook 显示一次。 - 再次设置 URL 会签发新的密钥;将 URL 设为 null 则关闭转发。
- 每个事件仅发送一次,最长等待 8 秒,不跟随重定向,且只发送到解析为公网 IP 的 HTTPS 地址。
- 删除连接会取消该账户的 Meta Webhooks 订阅,并清除其端点和密钥。
import hashlib, hmac, time
def verify_ec_signature(raw_body: bytes, header: str, secret: str) -> bool:
"""Check X-EC-Signature on an event forwarded by easyCoexistence."""
parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
t, v1 = parts.get("t", ""), parts.get("v1", "")
if not t.isdigit() or abs(time.time() - int(t)) > 300:
return False # missing, malformed or older than 5 minutes
expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected.encode(), v1.encode())常见错误
- 以 JSON 或加引号的形式返回 challenge。Meta 要求正文就是 hub.challenge 的值本身,状态码为 200。
- 对解析后的正文进行哈希。JSON 解析器会丢弃 Meta 签名所针对的原始字节,因此应保留原始正文用于 HMAC,之后再解析。
- 只订阅了应用却忘了账户。在某个账户的 POST /<IG_ID>/subscribed_apps 成功之前,该账户不会收到任何通知。
- 让端点故障持续一小时。Meta 会停用消息 Webhooks,并取消应用对该账户的订阅,需要重新订阅。
签名密钥按账户单独配置,同时全天候监控每个连接。使用 set_social_webhook_destination 或 Partner API 即可开启。每个连接每月 US$ 9 降至 US$ 0.75,连接越多单价越低,前 3 天免费试用。
常见问题
Instagram Webhook 中的 hub.challenge 是什么?
Meta 在验证 GET 请求中发送的整数。端点核对 hub.verify_token 后,将其作为响应正文返回,以证明自己控制该 URL。
为什么 PHP 中没有 hub.mode 和 hub.challenge?
PHP 会将参数名中的点换成下划线,因此 Meta 的验证值会以 hub_mode、hub_challenge 和 hub_verify_token 的形式到达。
Meta 停用 Instagram Webhook 后,如何重新开启?
修复端点,然后使用相同字段执行 POST /<IG_ID>/subscribed_apps,重新订阅该账户。
自签名证书能用于 Instagram Webhook 端点吗?
不能。Meta 不支持自签名证书:回调 URL 必须可通过 HTTPS 访问并使用有效证书,这是 Meta 故障排查清单的第一项。
继续阅读
两分钟连接您的第一个渠道。
无需等待平台审核。连接 WhatsApp、Instagram、TikTok 或其他渠道,然后让您的 AI 发布、回复或生成报告,看它如何运作。
- 免费试用 3 天
- 随时取消
- 仅使用官方 API
- 全天候 24/7 监控
验证时间