Webhook 設定 完全ガイド（IG Harness セットアップ編 #4）

IG Harness が DM・コメント・ストーリーメンションを受信するのは全て Webhook 経由。ここの設定ミスで「コード書いたのに全く動かない」になるので、設定項目と踏んだ罠を全部書く。

Webhook の全体像

[IG ユーザーがコメント] 
    ↓
[Meta サーバー] 
    ↓ POST https://ig-harness.workers.dev/webhook
[Worker] signature 検証 → 処理 → return 200

Meta 側で設定する必要があるもの:

1. アプリレベル: コールバック URL、verify token、フィールド選択
2. アカウントレベル: subscribed_apps エンドポイントを直接叩いて登録（これが抜けてて動かない率高い）
3. Worker の secret: IG_VERIFY_TOKEN と IG_APP_SECRET

ステップ1: Worker に /webhook エンドポイントを用意

// GET /webhook — Meta verification challenge
webhook.get('/webhook', (c) => {
  const mode = c.req.query('hub.mode');
  const token = c.req.query('hub.verify_token');
  const challenge = c.req.query('hub.challenge');
  if (mode === 'subscribe' && token === c.env.IG_VERIFY_TOKEN) {
    return c.text(challenge, 200);
  }
  return c.json({ error: 'Verification failed' }, 403);
});

// POST /webhook — Instagram events
webhook.post('/webhook', async (c) => {
  const rawBody = await c.req.text();
  const signature = c.req.header('X-Hub-Signature-256') ?? '';
  const valid = await verifyWebhookSignature(rawBody, signature, c.env.IG_APP_SECRET);
  if (!valid) {
    // 開発モードは素通りで OK、本番は reject 推奨
    console.warn('Signature verification failed');
  }
  // ... event 処理
  return c.json({ status: 'ok' }, 200);
});

ステップ2: Worker に verify token と app secret を投入

# verify token は任意のランダム文字列（Meta と一致させるだけ）
VERIFY_TOKEN=$(openssl rand -hex 16)
printf '%s' "$VERIFY_TOKEN" | wrangler secret put IG_VERIFY_TOKEN

# app secret は Dashboard の「基本」→「Instagram アプリシークレット」をコピー
printf '%s' "<APP_SECRET_HEX>" | wrangler secret put IG_APP_SECRET

VERIFY_TOKEN の値はクリップボードにコピーしておく（次のステップで Meta Dashboard に入力する）。

ステップ3: Meta Dashboard で Webhook URL 設定

左メニュー「Instagram」→「API setup」→ **ステップ3「Webhooks を設定する」**セクション:

項目	入力内容
コールバック URL	https://<your-worker>.workers.dev/webhook
トークンを認証	上で生成した VERIFY_TOKEN の値

「保存」を押すと Meta が GET /webhook を叩いて verify token を確認する。正しければ登録完了。

保存時のエラー

• 「URL の認証に失敗しました」→ Worker の verify token と Meta の入力値が一致していない（改行混入の可能性も確認）
• 「URL に到達できません」→ Worker が deploy されていない、または URL のタイポ

ステップ4: フィールド選択（サブスクライブ）

同じ Webhooks セクションの「Webhook フィールド」テーブル:

フィールド	推奨	用途
messages	⭕️	DM 受信
messaging_postbacks	⭕️	クイックリプライ・ボタン押下
messaging_seen	🔶	既読
messaging_optins	🔶	オプトイン
messaging_referral	🔶	外部リンクからのDM開始
messaging_handover	🔶	他アプリとの受け渡し
comments	⭕️	投稿コメント
live_comments	🔶	ライブ配信コメント
mentions	⭕️	ストーリーメンション
standby	🔶	他アプリが primary な時の待機イベント
message_edit	🔶	DM 編集
message_reactions	🔶	DM リアクション
agentic_message	⭕️ / 🔶	AI エージェント機能用（必要に応じて）

各行の「サブスクリプション登録」ボタンでトグル。最低 messages、messaging_postbacks、comments、mentions を ON にする。

ステップ5: アカウントレベル subscribed_apps（ここが罠）

アプリレベルの Webhook 設定だけでは、実は webhook が飛んでこない。これに加えて、紐付けた IG ビジネスアカウント単位で subscribed_apps エンドポイントに POST する必要がある:

TOKEN="IGAA..."  # ステップ3 で取得したアクセストークン
IG_USER_ID="<IG_USER_ID>"

curl -X POST "https://graph.instagram.com/v25.0/${IG_USER_ID}/subscribed_apps?subscribed_fields=messages,messaging_postbacks,comments,mentions&access_token=${TOKEN}"

レスポンス: {"success":true}

これを忘れると「Dashboard 上は設定済みに見えるのに、コメントしても何も起きない」状態に陥る。Meta のドキュメントにも小さく書いてあるだけで気づきにくい。

登録状態の確認

curl "https://graph.instagram.com/v21.0/${IG_USER_ID}/subscribed_apps?access_token=${TOKEN}"

レスポンス例:

{"data":[{"id":"17879...","subscribed_fields":["messages","messaging_postbacks","comments","mentions"]}]}

data が空配列ならまだ登録されてない。

踏んだ罠: Worker リネームで URL が古いまま

Worker 名を変えた時（例: instagram-harness → ig-harness）、.workers.dev サブドメインも変わる:

旧: https://<old-worker-name>.workers.dev/webhook
新: https://<your-ig-worker>.workers.dev/webhook

Meta Dashboard の Webhook URL は自動更新されない。旧 URL のまま残ると、Meta は webhook を旧 URL に送り続け、Worker 不在で 404 扱い → 何日かリトライして諦める。

症状:

• messages_log に新着データが来ない
• Graph API でコメント取得するとちゃんと見える（= Meta 側では受信済み）
• 一般 webhook はサイレントに失敗する

対策: Worker 名を変更したら即 Meta Dashboard で URL 書き換え + 保存ボタン（verify token 再認証）。

踏んだ罠: verify token の改行混入

echo "token" | wrangler secret put IG_VERIFY_TOKEN だと値に \n が入って、Meta からの verify 時に文字列比較で不一致 → 「URL 認証失敗」。

対策: printf '%s' "token" を使う。詳細は デバッグ編 参照。

踏んだ罠: ManyChat が webhook を奪う

同じ IG アカウントに ManyChat 等の別アプリが連携していると、webhook の primary receiver を奪われることがある。IG Harness 側には standby として配信されるだけで、主動作が妨げられる。

解決策:

# 1. ManyChat を明示的に解除（IG Harness を primary にする）
curl -X DELETE "https://graph.instagram.com/v25.0/${IG_USER_ID}/subscribed_apps?access_token=${TOKEN}"

# 2. 再度 IG Harness を登録
curl -X POST "https://graph.instagram.com/v25.0/${IG_USER_ID}/subscribed_apps?subscribed_fields=messages,messaging_postbacks,comments,mentions&access_token=${TOKEN}"

これで IG Harness が primary になる。ManyChat は standby（バックアップ）扱いになり、両方共存も可能。

チェックリスト

• Worker に /webhook の GET と POST ハンドラ実装済み
• IG_VERIFY_TOKEN と IG_APP_SECRET を printf で投入
• Meta Dashboard でコールバック URL と verify token を設定、保存に成功
• Webhook フィールドで messages, messaging_postbacks, comments, mentions をサブスクライブ
• subscribed_apps を curl で POST 登録
• subscribed_apps を GET で登録状態確認

次は webhook が届かない時のデバッグ へ。