Webhook が届かない時のデバッグ完全ガイド（IG Harness セットアップ編 #5）

「セットアップしたのに webhook が全く来ない」「コメント書いても DM が飛ばない」時の切り分け手順。実際に詰まった症状と原因の対応表込みで書く。

切り分けの基本方針

Webhook が届かない原因は大きく5つ:

1. Meta 側にイベント自体が届いていない（IG の API カーブ or アカウント問題）
2. Meta は受信してるが Worker に送ってない（Dashboard 側設定不備）
3. Meta から Worker に POST されてるが Worker が reject（URL ミスマッチ、署名検証失敗）
4. Worker は受信してるがイベント処理でエラー（DB・コード不具合）
5. 処理は成功してるが DM 送信が失敗（token 失効、permission 不足）

切り分けはこの番号順で上から確認していく。

Step 1: Meta にイベントが届いてるか — Graph API で確認

まず IG のコメント API を叩いて、Meta 側にイベントが記録されているか確認:

TOKEN="IGAA..."
POST_ID="<TARGET_POST_ID>"  # テスト対象のポストID

curl -s "https://graph.instagram.com/v21.0/${POST_ID}/comments?fields=id,text,timestamp&limit=10&access_token=${TOKEN}"

返ってきた data 配列に該当コメントがあれば、Meta までは届いてる。

• 返らない・空 → IG 側の問題（アカウントがシャドウバン、ポスト ID 誤り、token 権限不足）
• 返ってる → 次の Step へ

Step 2: subscribed_apps の登録状態を確認

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 が空 → Webhook 設定記事 #4 のステップ5 でアカウントレベル登録
• subscribed_fields に comments がない → 再 POST でサブスクライブ
• data に別アプリの id（ManyChat 等）だけ入っている → 別アプリが primary、奪い取り必要

Step 3: Worker に POST が届いているか — wrangler tail

cd apps/worker
pnpm wrangler tail --format=pretty

別 terminal からテスト用コメントを投下。tail に以下のような出力が来るかチェック:

POST https://ig-harness.workers.dev/webhook - Ok @ ...
  (log) Webhook received, raw body: {"entry":...
  (log) Webhook object: instagram entries: 1

• POST が一切来ない → Meta Dashboard の Webhook URL が古い / 間違っている
• POST 来るが 4xx/5xx を返す → 署名検証 or ハンドラでエラー
• 200 を返しているが処理が始まらない → コード側の分岐問題

Step 4: Webhook URL が古くないか

Worker 名を変更すると .workers.dev サブドメインが変わる。Meta Dashboard 側は自動更新されないので要確認。

旧 Worker 名 instagram-harness → URL: https://instagram-harness.workers.dev/webhook
新 Worker 名 ig-harness       → URL: https://ig-harness.workers.dev/webhook

Dashboard のコールバック URL を直接見て確認。手動で curl テスト:

curl -i "https://<dashboard に入ってるURL>/webhook?hub.mode=subscribe&hub.verify_token=test&hub.challenge=xxx"

• 404 or CF エラーページ → URL が古い / Worker 不在 → Dashboard 側更新
• 200 test が返る → verify token 不一致（Worker 側と入力値が違う or 改行混入）
• 200 xxx が返る → Worker 側 OK

Step 5: verify token の改行確認

echo でセットした secret は末尾に \n が付いてる可能性がある:

// Worker 側のコード
if (token === c.env.IG_VERIFY_TOKEN) { ... }
// token は "test" だけど env.IG_VERIFY_TOKEN は "test\n" → 一致しない

対策: printf '%s' で再投入

printf '%s' "your_verify_token" | wrangler secret put IG_VERIFY_TOKEN

これは verify token 以外の全 secret（URL、API key、HMAC secret 等）にも言える。

URL に改行が入ると: https://ig-harness.workers.dev\n/api/followers/link-line になり、改行が %0A にエンコードされて 404 + Cloudflare Error 1042 になる。実際踏んだ。

Step 6: App Mode を確認

Dashboard 右上のトグルを確認:

• Development Mode → テスターロール持ちの IG アカウントからしか webhook 来ない
• Live → 全ユーザーから webhook 来る

「テストしている IG アカウントはテスター？ Live モード？」を切り分けに使う。

Step 7: Worker のコードでログを仕込む

それでも何が起きてるか分からない時は /webhook ハンドラの最初でログを仕込む:

webhook.post('/webhook', async (c) => {
  const rawBody = await c.req.text();
  console.log('Webhook received, raw body:', rawBody.substring(0, 500));
  console.log('Headers:', Object.fromEntries(c.req.raw.headers));
  // ... 既存処理
});

デプロイしてから wrangler tail。raw body と headers を見ることで、Meta が何を送っているか具体的に把握できる。

Step 8: DM 送信が失敗する場合

Webhook は受信できてる、CTA DM も送信処理は走ってる、でもユーザーに届かない場合:

エラーコード 2534014: 「ユーザーが見つかりません」

• 送信先 IGSID が誤り
• そのユーザーが過去24時間以内に何らかのアクションしていない（messaging window 切れ）
• Human Agent permission が未取得

エラーコード 2534037: 「スレッド所有者ではない」

• 別アプリ（ManyChat等）が primary receiver
• subscribed_apps を奪い返すと解決

token 失効

• 60 日経過 → /refresh_access_token で延長、または Meta Dashboard で再発行
• /me?access_token=X で {"error":{"type":"OAuthException"}} が返るなら失効

症状→原因 早見表

症状	確認順	典型的原因
コメントしても何も起きない	Step 1 → 2 → 3	subscribed_apps 未登録、Webhook URL 古い
GET /webhook 認証で失敗	Step 5	verify token 改行混入
「URL が無効」で保存できない	Step 4	Worker 未 deploy、URL タイポ
一部ユーザーからだけ届く	Step 6	Development モードでテスターのみ
webhook 来てるが DM 送信失敗	Step 8	token 失効、messaging window、primary 奪われた
数日動いてたのに突然止まった	Step 8 → 1	60日経過で token 失効

tail の結果を読む小技

wrangler tail --format=pretty でログは流れるが、長時間回すと埋もれる。特定イベントだけ拾いたい場合:

pnpm wrangler tail --format=pretty 2>&1 | grep -iE "webhook|comment|dm"

--format=json で JSON 出力して jq でフィルタするのも可。

チェックリスト — 動かない時にやる順番

1. Graph API で対象イベントが Meta 側で見えるか
2. subscribed_apps に自アプリが登録されていて comments / messages がサブスクライブされてるか
3. wrangler tail で POST /webhook が来ているか
4. Meta Dashboard の Webhook URL が現行 Worker URL と一致するか
5. Verify token の改行混入を printf で再投入して修正
6. App Mode が Live か（Development なら本番テスト不可）
7. Token が失効していないか（/me?access_token=X で確認）
8. messaging window 内か（24時間ルール）

シリーズ一覧

• #1: Meta アプリ作成〜Live公開 完全ガイド
• #2: プライバシーポリシー・利用規約 URL セットアップ
• #3: Instagram アカウント紐付け・アクセストークン取得
• #4: Webhook 設定 完全ガイド
• #5: このページ
• 連携編: IG Harness × LINE Harness 連携