監視と失敗時の対応

Webhook 監視アラートデッドレター障害対応

この記事の対象
Webhookを本番運用する開発者・運用担当者向けです。配信状況の確認方法、監視すべき指標、障害発生時の復旧手順を説明します。

Webhookは「動いている時は静か」な仕組みです。だからこそ問題が起きていることに気づきにくく、気づいた時には数日分のイベントが取り逃がし、ということが起こりがちです。本番運用では能動的な監視が欠かせません。

開発者ポータルの配信履歴

開発者ポータル → アプリ → Webhook → 該当エンドポイント → 「配信履歴」タブで、過去30日間の配信結果を確認できます。

表示される情報

配信日時、イベントID、イベント種別
最終ステータス（成功 / 再試行中 / デッドレター）
各試行のHTTPステータスコード、応答時間、レスポンスボディ（先頭1KB）
「再配信」ボタン（手動で再送可能）

絞り込み

ステータス（成功のみ／失敗のみ／デッドレターのみ）
イベント種別
期間（過去24時間／7日／30日）
イベントID／受信URL部分一致

監視すべき指標

本番運用で最低限ウォッチすべき指標です。開発者ポータルの「Webhookダッシュボード」で確認できるほか、自社の監視基盤に取り込むことを推奨します。

指標	アラート閾値の例	意味
成功率（直近1時間）	99% を下回ったら通知	エンドポイントの可用性
P95応答時間	3秒を超えたら警告	処理性能の劣化検知
デッドレター件数（24時間）	1件でも発生したら通知	取り逃がしたイベントの存在
再送中件数	100件を超えたら警告	受信側の継続的な失敗
タイムアウト発生率	1% を超えたら警告	受信側の処理が重すぎる兆候

受信側で持つべきメトリクス

送信側の監視に加え、受信側でも次のメトリクスを取ると原因特定が早くなります。

受信件数（イベント種別ごと）
署名検証失敗回数（増えたらシークレット不一致や攻撃の可能性）
冪等性スキップ件数（再送が増えていないかの目安）
処理時間ヒストグラム（10秒タイムアウトに近づいていないか）
業務処理エラー率（再送ループの原因になる）

アラート通知先の設計

アラートは「気づける」だけでなく「対応できる」形で設計します。

営業時間中：Slack の運用チャンネル
夜間・休日：オンコール担当に PagerDuty / Opsgenie 等で通知
軽度の警告：日次サマリーメールに集約
デッドレター発生：即時通知＋週次レビュー

デッドレターの再配信

7回の自動再送に失敗したイベントは「デッドレター」として保存されます。原因を修正したあと、次の手順で再配信できます。

配信履歴で「デッドレター」フィルタを選択
個別に「再配信」ボタンをクリック、または複数選択して「一括再配信」
結果を配信履歴で確認

デッドレターは配信から30日間保持されます。30日を超えると消えるので、それより前に対応するか、API で過去データを取り直してください。

よくある障害パターンと対処

1. 全Webhookが `5xx` で失敗している

受信側サーバーがダウンしていないか確認
直近のデプロイが原因の可能性 → ロールバック検討
復旧後、デッドレターを「一括再配信」

2. 一部のイベント種別だけ失敗

該当イベント用の処理ロジックにバグがある可能性
配信履歴のレスポンスボディからスタックトレースを確認
受信側ログで該当 event_id を検索

3. `401`（署名検証失敗）が増えた

シークレットを再生成した直後で旧シークレットがまだ動いていないか
環境変数の反映漏れ（再起動忘れ）
本番／ステージングのシークレットを取り違えていないか

4. タイムアウトが頻発

受信側の処理が重い → 内部キューに投入する設計に変更
下流DBや外部APIの遅延 → 一時的に該当処理をバイパス
受信エンドポイントのスケール不足 → インスタンス数を増やす

5. Webhookが全く来ない

エンドポイントが「無効」になっていないか
購読イベントが正しく選択されているか
対象店舗フィルタで自分が除外されていないか
受信URLが外部から到達可能か（社内VPN内になっていないか）

定期メンテナンスのチェックリスト

月1回程度、次の項目をレビューすることを推奨します。

☐ 過去1か月のデッドレター件数と原因
☐ 成功率の推移（劣化していないか）
☐ P95応答時間の推移
☐ シークレットの最終更新日（年1回ローテーションが目安）
☐ 不要になったエンドポイントの削除
☐ 購読イベントの整理（使っていないものを外す）

サポートへの問い合わせ

原因が特定できない場合や、レシートローラー側の障害が疑われる場合は、開発者コミュニティかサポート窓口へ問い合わせてください。問い合わせ時は次の情報を添えるとスムーズです。

アプリID（クライアントID）とエンドポイントID
事象が発生した日時範囲（UTC または JST 明記）
影響を受けた event_id をいくつか
受信側のレスポンスコードとログ抜粋