Instagram Webhook イベント:コメント、メンション、DM
Instagram Webhook イベントは、プロフェッショナルアカウントで起きた活動を、発生と同時に報告します。新しいコメント、@メンション、DM が対象です。Meta は各イベントを JSON として接続済みアプリの HTTPS エンドポイントに POST し、失敗した配信を同じエンドポイントに対して最長 36 時間まで再試行します。easyCoexistence は各イベントを、アカウントごとに署名を付けて、お使いのエンドポイントへ 1 回だけ転送します。再試行はありません。Instagram Login の場合、メンションはコメントの通知に含まれて届きます。
Meta が失敗した配信をアプリのエンドポイントへ再試行し、その後破棄するまでの期間。
多くの更新は Meta によって 1 回の Webhook 配信にまとめられますが、まとめられることは保証されていません。
アカウント自身が送ったメッセージのイベントに Meta が付けるフラグ。
コメントとメンションの通知が発生するのは、公開アカウントのメディアだけです。
イベントの種類
プロフェッショナルアカウントを 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 配列が入ります。新しいコメントは次のような形になります:
{
"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 分より古いタイムスタンプは拒否してください。
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 は、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 監視
確認日