Webhookが届かない

トラブル Webhook 配信

売上や受注があったはずなのに、Webhookが受信URLに届かないときの確認手順です。まずテスト送信と配信ログで「レシートローラーが送っていないのか」「送ったが受信側で失敗しているのか」を切り分け、それぞれの原因を順に確認します。

テスト送信で受信側を確かめる

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

結果	意味
`success: true`	受信側は正常です。「配信ログに記録がない」の項目を確認します
`httpStatus: 0`	接続できないか、10秒以内に応答がありません。「接続できない」の項目へ
`httpStatus: 401` など	届いているが受信側が拒否しています。「受信側が拒否している」の項目へ
APIが `404`	Webhook IDが違うか、別のアプリのトークンを使っています

テスト送信は、購読イベントや有効／無効の状態に関係なく1回だけ送られます。開発者ポータルの画面にはテスト送信のボタンはないため、APIで行います。

配信ログを見る

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

直近50件の試行が新しい順に返ります。届かなかったはずの時刻の前後に行があるかどうかで、次に見る項目が決まります。

行がない：レシートローラーが送っていません →「配信ログに記録がない」
行があり success: false：送ったが失敗しています → httpStatus に応じて「接続できない」または「受信側が拒否している」

配信ログに記録がない

Webhookが無効になっていないか：GET /api/v1/webhooks/{webhook_id} の active、または開発者ポータルのアプリ詳細で「無効」になっていないか確認します。4回続けて配信に失敗すると自動で無効になり、その間のイベントは送られません。直したら PATCH で { "active": true } を送るか、画面の再開ボタンで有効に戻します
送信されるイベントを購読しているか：実際に送られるのは receipt.created、order.created、order.updated だけです。receipt.updated、receipt.deleted、coupon.redeemed、coupon.expired、customer.visited は購読できても送られません
ビジネスアカウントが合っているか：Webhookは登録したときのビジネスアカウント（APIならトークンのビジネスアカウント、画面ならアプリを持つビジネスアカウント）のイベントだけを受け取ります。GET /api/v1/webhooks/{webhook_id} の organizationId を確認します
その操作でイベントが起きるか：receipt.created は売上が初めて保存されたときだけ送られます。POSからの同じ売上の再送、再同期、同じ期間のCSVの再取り込み、削除された売上では送られません。受注のイベントは受注管理での作成・編集・確認・処理開始・キャンセル・POSでの受け渡しで送られます
レシートローラー側の再起動：再送の待ち時間はサーバー上で保持されているため、その間にサーバーが再起動すると残りの再送は行われません。この場合は配信ログに失敗の行が残ったまま止まります。抜けた期間はAPIで取り直してください

接続できない（httpStatus が 0）

errorMessage に理由が入っています。

受信URLがインターネットから届くか（社内ネットワークやVPNの中にないか、サーバーが動いているか）
TLS証明書が有効か（期限切れや自己署名ではないか）
ファイアウォールやWAFが外部からの POST を止めていないか
10秒以内に応答しているか。重い処理は応答のあとに回します（再送・順序・冪等性の設計）
受信URLのホスト名やパスを変えていないか。登録したURLはあとから変えられないので、変えた場合は新しいURLでWebhookを登録し直します

受信側が拒否している（4xx・5xx）

401 / 403：多くは署名検証の失敗です
- Webhook登録時のシークレットを使っているか（クライアントシークレットではありません）
- JSONにパースする前の生のボディで計算しているか
- sha256= と小文字の16進文字列で比較しているか
- 2026年10月23日の修正より前に登録したWebhookは、アプリのクライアントIDで署名されています。登録し直すとシークレットで署名されます
404 / 405：受信側のルーティングで、そのパスの POST を受け付けていません
5xx：受信側の処理でエラーになっています。受信側のログで、同じ時刻の X-RR-Delivery を探します

詳しくは署名検証とセキュリティを参照してください。

届かなかったイベントを取り戻す

過去のイベントをレシートローラーから再送する機能はありません。受信側を直してWebhookを有効に戻したあと、届かなかった期間の売上を取引一覧APIで取得して補ってください。