監視と失敗時の対応

Webhook 監視配信ログ障害対応

Webhookは動いている間は静かなので、止まっても気づきにくい仕組みです。しかも4回続けて配信に失敗するとWebhookは自動で無効になり、その間のイベントは届きません。この記事では、レシートローラーで確認できる配信の状態と、止まったことに早く気づいて復旧する方法を説明します。

確認できる情報

情報	どこで見るか	わかること
`active`	`GET /api/v1/webhooks/{id}`、開発者ポータルのアプリ詳細（有効／無効）	`false` なら配信が止まっています。一時停止したか、4回続けて失敗して自動で無効になりました
`lastDeliveredAt`	`GET /api/v1/webhooks/{id}`、アプリ詳細の「最終送信」	最後に配信が成功（`2xx`）した日時（UTC）。テスト送信では更新されません
配信ログ	`GET /api/v1/webhooks/{id}/deliveries`	直近50件の試行ごとの結果

配信ログは開発者ポータルの画面には表示されません。APIで取得します。

配信ログの見方

curl https://receiptroller.io/api/v1/webhooks/{webhook_id}/deliveries \
  -H "Authorization: Bearer {access_token}"

[
  {
    "id": "wdl_xxxxxxxxxxxx",
    "webhookId": "wh_xxxxxxxxxxxxxxxx",
    "eventType": "receipt.created",
    "httpStatus": 503,
    "success": false,
    "attemptCount": 2,
    "errorMessage": null,
    "attemptedAt": "2026-10-26T03:16:44.0000000"
  }
]

試行1回につき1行で、新しい順に最大50件が返ります。期間や状態で絞り込むパラメーターはありません
attemptCount はそのイベントの何回目の試行か（1〜4）です
httpStatus は受信側が返したステータスです。0 は接続できなかった、または10秒以内に応答がなかったことを示し、errorMessage に理由が入ります
attemptedAt はUTCです
イベントID（X-RR-Delivery）、ボディ、受信側のレスポンスボディは記録されません。どのイベントの試行かを突き合わせるには、受信側で X-RR-Delivery と受信時刻をログに残してください
テスト送信は記録されません

止まったことに気づく

レシートローラーからWebhookの失敗や無効化を知らせる通知は届きません。自分の側で次のように見張ります。

無効化の検知：定期的に GET /api/v1/webhooks を呼び、active が false のものがあれば通知する。もっとも大事な監視です
失敗の増加：配信ログで success: false の行や、attemptCount が2以上の行が続いていないかを見る
届かなくなったこと：営業時間中に lastDeliveredAt が長く更新されていなければ、受信側か連携元に問題がある可能性があります
受信側の記録：受信件数（イベントごと）、署名検証の失敗件数、重複として捨てた件数、応答までの時間を残すと、原因を早く絞り込めます

止まったときの復旧

配信ログの httpStatus と errorMessage から原因を確認し、受信側を直します
テスト送信（POST /api/v1/webhooks/test/{id}）で success: true になることを確かめます。テスト送信は無効になっているWebhookにも送れます
PATCH /api/v1/webhooks/{id} に { "active": true } を送るか、開発者ポータルの再開ボタンで有効に戻します
止まっていた間のイベントは届かないので、その期間の売上を取引一覧APIで取得して補います

よくある原因

配信ログ	考えられる原因
`httpStatus: 0`	受信URLに届かない（DNS、TLS証明書、ファイアウォール、サーバー停止）か、10秒以内に応答していない
`401` / `403`	受信側で署名検証に失敗している。シークレットの取り違えや、生のボディで計算していないことが多い（署名検証とセキュリティ）
`404`	受信URLのパスが変わった。URLはあとから変えられないので、新しいURLでWebhookを登録し直す
`5xx`	受信側の処理が失敗している。重い処理や外部サービスへの送信を応答の後に回す（再送・順序・冪等性の設計）
記録がない	配信されていない。Webhookが届かないを参照

定期的に見直すこと

使っていないWebhookを削除する
送信されないイベント（receipt.updated など）だけを購読しているWebhookがないか確認する
Webhookとの突き合わせに使うAPIでの定期取得が動いているか確認する