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

Instagram Webhook 事件:评论、提及与私信

Instagram Webhook 事件会实时报告专业账户上的活动:新评论、@提及和私信。Meta 会以 POST 请求将每条事件(JSON 格式)发送到已连接应用的 HTTPS 端点,并在投递失败时对该端点最多重试 36 小时。easyCoexistence 会将每条事件向您的端点转发一次,按账户签名,不进行重试。使用 Instagram Login 时,提及会包含在评论通知中。

36 hours

Meta 放弃前会对应用端点的失败投递重试多长时间。

1,000

大多数更新 Meta 会合并为一次 Webhook 投递,但并不保证合并。

is_echo

Meta 为账户自己发出的消息事件设置的标记。

Public

只有公开账户的媒体会触发评论和提及通知。

有哪些事件?

对于使用 Instagram Login 连接的专业账户,有三类活动会以事件形式到达:

  • 评论:账户媒体上的新评论,包含评论 ID、作者的 Instagram 范围 ID 和用户名、文本,以及媒体 ID 和类型。
  • 提及:使用 Instagram Login 时,提及包含在评论通知内,而不是独立的字段。
  • 消息:发给账户的私信,包含发送方、接收方、时间戳和消息本身,包括文本、附件和限时动态回复。

事件如何到达您的端点?

Meta 将 Instagram Webhook 投递到账户所连接的应用。easyCoexistence 接收这些事件,并在事件到达时,将每条事件转发到您为该账户设置的 HTTPS 端点,并使用该账户专属的密钥签名。

可以通过 Claude 或 ChatGPT 中的 set_social_webhook_destination 设置端点,也可以通过 Partner API 使用 PUT /channels/:id/webhook 设置。签名密钥只显示一次,重新设置端点会生成新的密钥,将 URL 设为 null 则会关闭转发。

投递内容是什么样的?

这是一个 POST 请求,请求体为 JSON,其中包含平台、list_social_accounts 返回的连接 account_id、Instagram 账户的 external_id,以及 entry:Meta 为该事件返回的 Webhook entry,原样保留。私信以相同方式到达,只是用 messaging 数组代替 changes。新评论的样例如下:

A forwarded comment event
{
  "platform": "instagram",
  "account_id": "<ACCOUNT_ID>",
  "external_id": "<INSTAGRAM_ACCOUNT_ID>",
  "entry": {
    "id": "<INSTAGRAM_ACCOUNT_ID>",
    "time": 1793318400,
    "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 标头,格式为 t=<unix>,v1=<hex>。其中 v1 是时间戳、点号(.)和原始请求体组成的字符串的 HMAC-SHA256 值,以该账户的签名密钥为密钥计算。请对按原样收到的原始请求体计算签名,以恒定时间比较,并拒绝早于 5 分钟的时间戳。

Node.js: verifying X-EC-Signature
import crypto from "node:crypto";

// rawBody: the request body exactly as received, as a string
export function verify(rawBody, header, secret) {
  const sig = Object.fromEntries(header.split(",").map((part) => part.split("=")));
  if (!sig.t || !sig.v1) return false;
  if (Math.abs(Date.now() / 1000 - Number(sig.t)) > 300) return false;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(sig.t + "." + rawBody)
    .digest("hex");
  return expected.length === sig.v1.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1));
}

投递失败会重试吗?

easyCoexistence 不会重试:转发时每条事件只传递一次,仅在内存中处理,不保留可用于重试的副本。请快速返回 2xx 响应,之后再处理,并在事件到达时保存所需的数据,因为 Meta 也不保留可查询的历史通知记录。

Meta 本身会对失败的应用投递重试最多 36 小时,因此同一事件偶尔可能送达两次:请根据评论 ID 或消息的 mid 去重。

处理程序还应检查什么?

Meta 的负载中有一些细节,首次编写处理程序时容易出错:

  • is_echo:is_echo 设为 true 的消息事件由账户自己发出,因此无需回复。
  • 限时动态回复:回复限时动态的私信会携带 reply_to,其中包含该限时动态的 ID 和 URL。
  • 限时动态提及:以附件类型为 story_mention 的消息到达。
  • time:Meta 发送通知的时间,而不是评论或消息创建的时间;消息自身的时间戳位于其 messaging 条目中。
  • 相册 ID:评论事件不包含相册 ID,请使用评论 ID 查询相册。

常见错误

  • 先做完工作再响应。转发不会重试,因此应立即返回 2xx,之后再处理事件。
  • 对解析后的 JSON 验证签名。应对原样到达的原始请求体计算 HMAC。
  • 回复回声。is_echo 设为 true 的消息事件是账户自己发出的,回复它会形成循环。
  • 跳过去重。失败后 Meta 可能再次投递同一事件,因此应以评论 ID 或消息的 mid 作为去重依据。
使用 EasyCoexistence 完成这些操作

easyCoexistence 会在 Instagram 账户的评论、提及和私信到达时,将其转发到您的 HTTPS 端点,并使用该账户专属的密钥签名,转发途中不保留任何副本。通过 Claude 或 ChatGPT 中的 set_social_webhook_destination,或通过 Partner API 即可开启。每个连接每月 US$ 9 起,连接越多越便宜,最低降至 US$ 0.75,首 3 天免费试用。

常见问题

Instagram Webhook 中的 time 字段是什么意思?

是 Meta 发送通知的时间,而不是评论或消息的创建时间。私信自身的时间戳位于其 messaging 条目中。

Meta 会重试失败的 Instagram Webhook 投递吗?

会。Meta 会对失败的应用投递重试最多 36 小时,因此同一事件偶尔可能送达两次:请根据评论 ID 或消息的 mid 去重。easyCoexistence 只会将每条事件转发到您的端点一次,因此请尽快返回 2xx 响应。

一次 Instagram Webhook 投递最多可包含多少条更新?

Meta 合并时最多可包含 1,000 条,但 Meta 不保证合并。请遍历整个 entry 数组,而不要只读取第一项。

提及有独立的事件吗?

使用 Instagram Login 时没有。Meta 将提及包含在评论通知中,因此它们与评论走相同的路径到达。

继续阅读

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

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

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

验证时间