登入開始免費試用
easyCoexistence 官方 API

Instagram webhook 事件:留言、提及及私訊

Instagram webhook 事件會即時回報專業帳戶的活動:新留言、@提及及私訊。Meta 會以 JSON 形式 POST 每項事件至已連接應用程式的 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 內容,其中包括:platform、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 的訊息事件是帳戶本身發出的,回覆它會引發循環。
  • 略過去重。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 監察

驗證日期