SuperAPI AI 工具集

facebook-webhooks

编程与开发

查看项目

更新于 10-15 22:14

技能介绍

用途:接收并验证 Facebook(Meta Graph API)Webhook,适用于搭建 Facebook Webhook 处理器、完成 GET 验证握手、排查签名验证失败,以及处理主页、Instagram 与 Messenger 事件。WhatsApp 虽共用同一 Meta 机制,但事件与负载不同,应使用专门的 whatsapp-webhooks 技能。

主要能力:同一端点承担两种请求。GET 为注册时一次性的验证握手,Meta 传入 hub.mode=subscribe、hub.verify_token、hub.challenge;当 verify_token 与应用面板中设置的 Verify Token 一致时,以 200 纯文本回显 hub.challenge。POST 为事件投递,Meta 发送 JSON 体 { object, entry[] },并用 X-Hub-Signature-256 签名。

签名验证:Meta 用 App Secret 对原始请求体做 HMAC-SHA256,摘要形如 sha256=<hex>。必须在 JSON 解析前对原始字节验证;Meta 签名的是转义 Unicode 形式的负载,重新序列化的 JSON 字符串无法匹配。旧版 X-Hub-Signature 用 SHA-1,应优先使用 SHA-256 头。

事件类型:Facebook 事件是 (object, field) 组合,而非点号名称。顶层 object 表示产品,entry[].changes[].field 表示变化,例如 page/feed、page/mention、page/messages、instagram/comments、instagram/mentions、user/feed 及 permissions。单个 POST 最多可批量 1000 条更新,需遍历 entry[] 逐条处理;Messenger 投递在每个 entry 上带 messaging 数组而非 changes。

使用方式与环境变量:FACEBOOK_APP_SECRET、FACEBOOK_VERIFY_TOKEN。本地开发可运行 npx hookdeck-cli listen 3000 facebook --path /webhooks/facebook,将隧道 URL 作为回调 URL 填入应用面板。注意 Development 模式应用只接收测试通知,主页订阅还需通过 POST /{page-id}/subscribed_apps 授予 pages_manage_metadata 权限。

限制与建议:应尽快返回 200 OK;失败投递会立即重试,随后频率递减,最长持续 36 小时,之后丢弃。建议同时安装 webhook-handler-patterns 技能,处理处理顺序、幂等、错误与重试逻辑。示例代码见 examples/express、examples/nextjs、examples/fastapi。