ログイン無料トライアルを開始
easyCoexistence 公式 API

Instagram Webhook イベント:コメント、メンション、DM

Instagram Webhook イベントは、プロフェッショナルアカウントで起きた活動を、発生と同時に報告します。新しいコメント、@メンション、DM が対象です。Meta は各イベントを JSON として接続済みアプリの HTTPS エンドポイントに POST し、失敗した配信を同じエンドポイントに対して最長 36 時間まで再試行します。easyCoexistence は各イベントを、アカウントごとに署名を付けて、お使いのエンドポイントへ 1 回だけ転送します。再試行はありません。Instagram Login の場合、メンションはコメントの通知に含まれて届きます。

36 hours

Meta が失敗した配信をアプリのエンドポイントへ再試行し、その後破棄するまでの期間。

1,000

多くの更新は Meta によって 1 回の Webhook 配信にまとめられますが、まとめられることは保証されていません。

is_echo

アカウント自身が送ったメッセージのイベントに Meta が付けるフラグ。

Public

コメントとメンションの通知が発生するのは、公開アカウントのメディアだけです。

イベントの種類

プロフェッショナルアカウントを Instagram Login で接続している場合、3 種類のアクティビティがイベントとして届きます:

  • コメント:アカウントのメディアへの新しいコメント。コメント ID、投稿者の Instagram スコープ ID とユーザー名、テキスト、メディア ID と種類を含みます。
  • メンション:Instagram Login の場合、メンションは独立したフィールドではなく、コメントの通知の中に含まれて届きます。
  • メッセージ:アカウントへの DM。送信者、受信者、タイムスタンプ、テキスト、添付ファイル、ストーリーへの返信を含むメッセージ本体。

イベントはエンドポイントにどう届くか

Meta は、アカウントが接続しているアプリへ Instagram の Webhook を配信します。easyCoexistence はそれを受け取り、届いたものから順に、そのアカウント用のシークレットで署名したうえで、そのアカウント用に設定された HTTPS エンドポイントへ転送します。

エンドポイントは Claude または ChatGPT から set_social_webhook_destination で、または Partner API の PUT /channels/:id/webhook で設定します。署名シークレットは一度だけ表示されます。エンドポイントを再度設定すると新しいシークレットが発行され、URL に null を渡すと転送が停止します。

配信の内容

JSON 本体を持つ POST で、プラットフォーム、list_social_accounts が返す接続の account_id、Instagram アカウントの external_id、そして Meta がそのイベントに付けた Webhook の entry がそのまま入ります。DM も同じ形で届きますが、changes の代わりに messaging 配列が入ります。新しいコメントは次のような形になります:

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 時間まで再試行するため、同じイベントが稀に 2 回届くことがあります。コメント ID またはメッセージの mid で重複を排除してください。

ハンドラーで確認すべきこと

初めてハンドラーを書く際につまずきやすい、Meta のペイロードの細かな点:

  • is_echo:is_echo が true のメッセージイベントは、アカウント自身が送ったものなので、返信は不要です。
  • ストーリーへの返信:ストーリーに対する DM には、ストーリーの ID と URL を含む reply_to が付きます。
  • ストーリーでのメンション:添付ファイルの種類が story_mention のメッセージとして届きます。
  • time:Meta が通知を送った時刻です。コメントやメッセージが作成された時刻ではありません。メッセージ自身のタイムスタンプは messaging エントリにあります。
  • アルバム ID:コメントイベントには含まれません。コメント ID を使ってアルバムを検索してください。

よくある間違い

  • 応答の前に処理すること。転送は再試行しないため、すぐに 2xx を返し、イベントは後で処理してください。
  • 解析済みの JSON で署名を検証すること。HMAC は届いたままの生の本体に対して計算してください。
  • is_echo が設定されたメッセージイベントに返信すること。それはアカウント自身が送ったもので、返信はループを引き起こします。
  • 重複排除を省くこと。失敗後に Meta が同じイベントを再度配信することがあるため、コメント ID またはメッセージの mid で判別してください。
EasyCoexistence で実現する

easyCoexistence は、Instagram アカウントのコメント、メンション、DM を、届いた順に HTTPS エンドポイントへ転送します。アカウントごとのシークレットで署名し、途中でコピーは保持しません。Claude または ChatGPT の set_social_webhook_destination、または Partner API で有効にできます。接続 1 件あたり月額 US$ 9 から US$ 0.75 まで、接続を増やすほど下がります。最初の 3 日間は無料です。

よくある質問

Instagram Webhook の time フィールドは何を指しますか

Meta が通知を送った時刻です。コメントやメッセージが作成された時刻ではありません。DM 自身のタイムスタンプは messaging エントリにあります。

Meta は失敗した Instagram Webhook 配信を再試行しますか

はい。Meta はアプリへの失敗した配信を最長 36 時間まで再試行するため、同じイベントが稀に 2 回届くことがあります。コメント ID またはメッセージの mid で重複を排除してください。easyCoexistence は各イベントをエンドポイントへ一度だけ転送するため、2xx をすぐに返してください。

1 回の Instagram Webhook 配信には、いくつの更新が含まれますか

Meta がまとめる場合は最大 1,000 件です。ただし Meta はまとめることを保証していません。entry 配列の先頭だけを読むのではなく、配列全体をループしてください。

メンションには独自のイベントがありますか

Instagram Login では、ありません。Meta はメンションをコメントの通知に含めるため、コメントと同じ経路で届きます。

続きを読む

最初のチャンネルを 2 分で接続しましょう。

プラットフォームの審査を待つ必要はありません。WhatsApp、Instagram、TikTok などのチャンネルを接続して、AI に投稿、返信、レポートを任せてみてください。

  • 3 日間無料
  • いつでも解約可能
  • 公式 API のみ使用
  • 24/7 監視

確認日