Instagram Webhook の確認: hub.challenge と X-Hub-Signature-256
Instagram の Webhook を設定するには、Meta の確認用 GET リクエストに応答する HTTPS エンドポイントが必要です。この GET には、値が subscribe の hub.mode、hub.verify_token、hub.challenge が含まれます。エンドポイントはトークンを確認し、challenge を返します。その後、アプリがフィールドを購読し、各アカウントを subscribed_apps エッジで購読すると、Meta はアプリのシークレットで署名された JSON イベントを POST します。署名は X-Hub-Signature-256 に入ります。
easyCoexistence は Meta 側を担当します。
Meta の確認リクエストには、hub.mode の値が必ず含まれます。
Meta が失敗した通知を頻度を下げながら再送し、破棄するまでの期間。
Meta が開発者アカウントへアラートを送るまでの、失敗したメッセージ配信の件数。
Webhooks Disabled アラートが出て、アプリがアカウントから購読解除されるまでの、失敗したメッセージ配信の件数。
ユーザーのアカウントの通知をアプリが受け取るために、Meta が求めるアプリモード。
Instagram Webhook の設定はどのような流れですか?
Meta のガイドが示す順に、4 つの手順で進みます。エンドポイントは、どのフィールドも選択できる前に確認を通過する必要があります。ユーザーのアカウントの通知を受け取るには、アプリが Live である必要があり、本番アクセスにはビジネス認証が必要です。
確認リクエストにはどのような内容が含まれますか?
コールバック URL への GET で、アプリダッシュボードで Webhooks 製品を設定するたびに送られます。hub.verify_token がエンドポイント自身のトークンと一致すると、レスポンスは 200 で、本文全体が hub.challenge の値になります。一致しなければ 403 を返します。ダッシュボードには、エンドポイントが確認に通ったかどうかが表示されます。
- hub.mode: 常に subscribe。
- hub.challenge: Meta が生成する整数で、エンドポイントはこれを返す必要があります。
- hub.
verify_token: ダッシュボードの「Verify Token」フィールドに入力する文字列です。Meta とエンドポイントだけが知っているべきです。 - PHP では、これらの名前のドットがアンダースコアに変わるため、値は
hub_mode、hub_challenge、hub_verify_tokenとして届きます。
GET https://<YOUR_HOST>/webhooks/instagram
?hub.mode=subscribe
&hub.challenge=1158201444
&hub.verify_token=<YOUR_VERIFY_TOKEN>
HTTP/1.1 200 OK
Content-Type: text/plain
1158201444コールバックとフィールドはどこで設定しますか?
アプリダッシュボードの「Instagram」配下にある「API setup with Instagram login」の「Configure webhooks」で設定します。コールバック URL と Verify Token をここに入力して保存すると、確認リクエストが送られます。Instagram 製品は、comments、live_comments、message_reactions、messages、messaging_optins、messaging_postbacks、messaging_referral、messaging_seen の購読から始まり、「Manage」でそのどれからも購読解除できます。「Test」ボタンは、選択したフィールドのサンプル通知を送信します。
X-Hub-Signature-256 はどのように確認しますか?
Meta は各イベント通知のペイロードを、アプリのシークレットをキーとする HMAC-SHA256 で署名します。その結果の 16 進数のダイジェストを sha256= に続けて X-Hub-Signature-256 に入れて送ります。受信側は、リクエスト本文の生のバイト列に対して同じ HMAC を計算し、ヘッダーの値と定数時間で比較します。Meta のメッセージングガイドによると、署名は Unicode をエスケープしたペイロードに対して計算されるため、デコードまたは再シリアライズした JSON をハッシュすると結果が変わります。
import crypto from "node:crypto";
import express from "express";
const app = express();
const { VERIFY_TOKEN, APP_SECRET } = process.env;
// Verification request: send hub.challenge back when the token matches
app.get("/webhooks/instagram", (req, res) => {
const ok = req.query["hub.mode"] === "subscribe" &&
req.query["hub.verify_token"] === VERIFY_TOKEN;
if (!ok) return res.sendStatus(403);
res.status(200).type("text/plain").send(req.query["hub.challenge"]);
});
// Event notification: check the signature over the raw bytes
app.post("/webhooks/instagram", express.raw({ type: "application/json" }), (req, res) => {
const expected = Buffer.from(
"sha256=" + crypto.createHmac("sha256", APP_SECRET).update(req.body).digest("hex")
);
const given = Buffer.from(req.get("X-Hub-Signature-256") ?? "");
if (given.length !== expected.length || !crypto.timingSafeEqual(given, expected)) {
return res.sendStatus(401);
}
res.sendStatus(200); // answer first, work after
const body = JSON.parse(req.body.toString("utf8"));
// hand body.entry to a queue or background job
});
app.listen(3000);なぜアプリのシークレットだけが検証できるのですか?
署名はそのシークレットをキーとする HMAC だからです。シークレットがなければ、期待される値を計算できる人はおらず、ペイロードのコピーを持っている人でも偽造はできません。そのため、確認はアプリ宛ての Meta のリクエストを受け取るサーバーで行う必要があります。Meta は、アプリのシークレット、アクセストークン、クライアント認証情報をログやサポートへの問い合わせに含めないよう求めています。他のアプリから転送されたイベントを受け取るシステムは、Meta の署名を確認できず、代わりにそのアプリ自身の署名に頼ることになります。
なぜアカウントごとに購読が必要なのですか?
アプリダッシュボードで設定するのはアプリが受け取れる内容であり、アカウントの通知は、そのアカウントも購読して初めて始まるからです。Instagram Login を使う場合は、アカウントの Instagram User アクセストークンとともに、graph.instagram.com へ POST /<IG_ID>/subscribed_apps を送ります。subscribed_fields には、アプリで選択したフィールドをカンマ区切りで指定します。成功すると、success が true で返されます。
POST https://graph.instagram.com/<IG_ID>/subscribed_apps
?subscribed_fields=comments,messages
&access_token=<INSTAGRAM_USER_ACCESS_TOKEN>
{ "success": true }配信に失敗すると Meta はどうしますか?
再送し、その後あきらめます。Meta のガイドは、各通知に 200 OK を返すよう求めており、最大 1,000 件の更新をまとめて送るバッチ処理は保証されないと警告しています。失敗した更新はすぐに再送され、その後 36 時間かけて頻度を下げながらさらに数回再送され、それでも失敗すると破棄されます。そのため、同じイベントが二度届くことがあります。メッセージングのイベントは、より速く動く Meta のメッセージング配信ルールに従います。
- 200 OK は 5 秒以内に返すことが期待されます。失敗した配信には即時に数回の再送が行われるため、メッセージの mid で重複を排除してください。
- 15 分間失敗が続くと、開発者アカウントにアラートが送られます。
- 1 時間失敗が続くと Webhooks Disabled アラートが出て、アプリは再度購読するまで、そのアカウントの Webhook から購読解除されます。
- 障害中に送られたメッセージは順序が入れ替わることがあるため、タイムスタンプで並べ替えてください。
何も届かないときは何を確認すべきですか?
大半の無反応なエンドポイントを扱う Meta のトラブルシューティングのチェックリストを、次の順に確認します:
- コールバック URL は確認を通過しており、有効な証明書で HTTPS により到達できること。自己署名証明書は非対応です。
- アプリが該当フィールドを選択し、必要なアクセスレベルを持っていること。comments と
live_commentsには「Advanced Access」が必要です。 subscribed_appsを通じてアカウントの通知が有効になっており、同じログイン設定で発行されたトークンが使われていること。- アカウントがフィールドのルールを満たしていること。コメント通知には、公開アカウントが所有するメディアが必要です。
- サーバーは、時間のかかる処理を始める前に success を返すこと。
なぜ easyCoexistence は転送するイベントに再び署名するのですか?
Meta の署名は転送できないからです。easyCoexistence のアプリは Meta からの配信を受け取り、独自のアプリシークレットで X-Hub-Signature-256 を確認し、すぐに Meta へ応答します。そのうえで、接続済みアカウントの各エントリを、そのアカウント用に設定されたエンドポイントへ POST します。送信するボディは、platform、account_id、external_id、entry を含む新しいものです。Meta のヘッダーは転送されず、そのシークレットがなければ確認もできないため、各転送には Content-Type: application/json と、そのアカウントだけに属するシークレットをキーとした X-EC-Signature を付けます。
X-EC-Signature はどのように確認しますか?
ヘッダーは t=<unix>,v1=<hex> の形式です。v1 は、タイムスタンプ、ドット、生のボディをつないだものに対する 16 進数の HMAC-SHA256 で、アカウントの署名シークレットをキーとします。受信した状態のバイト列そのままで再計算し、定数時間で比較し、5 分より古いタイムスタンプは拒否してください。
- シークレットは whsec_ で始まり、URL を設定する際に
set_social_webhook_destinationまたは PUT /channels/:id/webhook によって一度だけ表示されます。 - URL を再設定すると新しいシークレットが発行され、URL を null にすると転送は停止します。
- 各イベントは 1 回だけ送信されます。待機は最大 8 秒で、リダイレクトには従わず、パブリック IP に解決される HTTPS アドレスへ送られます。
- 接続を削除すると、そのアカウントは Meta の Webhook から購読解除され、エンドポイントとシークレットが消去されます。
import hashlib, hmac, time
def verify_ec_signature(raw_body: bytes, header: str, secret: str) -> bool:
"""Check X-EC-Signature on an event forwarded by easyCoexistence."""
parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
t, v1 = parts.get("t", ""), parts.get("v1", "")
if not t.isdigit() or abs(time.time() - int(t)) > 300:
return False # missing, malformed or older than 5 minutes
expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected.encode(), v1.encode())よくある間違い
- チャレンジを JSON として返したり、引用符で囲んだりすること。Meta はステータス 200 とともに、hub.challenge の値そのものを本文として期待しています。
- パース済みのボディをハッシュすること。JSON のボディパーサーは、Meta が署名した正確なバイト列を破棄するため、HMAC には生のボディを保持し、後からパースしてください。
- アプリを購読させ、アカウントを忘れること。POST /<IG_ID>/subscribed_apps がアカウントに対して成功するまで、そのアカウントの通知は一切届きません。
- エンドポイントを 1 時間にわたって失敗させたままにすること。Meta はメッセージングの Webhook を無効化し、アプリをアカウントから購読解除します。その後、再び購読し直す必要があります。
アプリは確認を通過し、X-Hub-Signature-256 を検証し、接続済みの各 Instagram アカウントをコメント、メッセージ、メンションに購読させます。イベントは、アカウントごとのシークレットで署名した X-EC-Signature を付けて、お使いの HTTPS エンドポイントへ転送します。各接続の状態を 24 時間体制で監視します。set_social_webhook_destination または Partner API で有効にできます。料金は接続 1 件あたり月額 US$ 9 から、接続を増やすほど下がり US$ 0.75 まで。最初の 3 日間は無料トライアルです。
よくある質問
Instagram Webhook の hub.challenge とは何ですか?
Meta が確認用の GET で送る整数です。エンドポイントは hub.verify_token を確認した後、これをレスポンスの本文として返し、URL を自分が管理していることを示します。
PHP では hub.mode と hub.challenge が見つからないのはなぜですか?
PHP はパラメータ名のドットをアンダースコアに変換するため、Meta の確認値は hub_mode、hub_challenge、hub_verify_token として届きます。
Meta が無効化した後、Instagram Webhook を再び有効にするには?
エンドポイントを修正してから、同じフィールドを指定して POST /<IG_ID>/subscribed_apps でアカウントを再度購読してください。
自己署名証明書は Instagram Webhook のエンドポイントで使えますか?
いいえ。Meta は自己署名証明書に対応していません。コールバック URL は、有効な証明書で HTTPS により到達できる必要があります。これは Meta のトラブルシューティングのチェックリストの最初の項目です。
続きを読む
最初のチャンネルを 2 分で接続しましょう。
プラットフォームの審査を待つ必要はありません。WhatsApp、Instagram、TikTok などのチャンネルを接続して、AI に投稿、返信、レポートを任せてみてください。
- 3 日間無料
- いつでも解約可能
- 公式 API のみ使用
- 24/7 監視
確認日