Webhook 失敗はなぜ起きる？よくある原因と対処法をわかりやすく解説

「Webhookを設定したはずなのに、決済成功の通知が届かない」「会員ステータスの更新が反映されていない」——PAY.JPのような決済代行会社のWebhookを導入した事業者・運用担当者であれば、こうしたWebhook失敗に一度は直面したことがあるかもしれません。

この記事では、Webhook失敗がどのような状態を指すのか、事業者側でよくある原因と、発生したときの対処法・再発防止のポイントを、非エンジニアの方にもわかるように解説します。

Webhook失敗とは

Webhookとは？で解説しているとおり、Webhook（ウェブフック）とは、決済代行会社側で何らかのイベントが発生したときに、あらかじめ登録しておいた事業者のURLへ自動的に通知が送られてくる仕組みです。この通知が正常に完了しない状態を指して、ここでは「Webhook失敗」と呼びます。

Webhook失敗には、大きく分けて2つのパターンがあります。

• 通知そのものが届かない：事業者側のエンドポイント（外部からのリクエストを受け取れるように公開したURL）が一時的に応答できない状態になっているケース
• 通知は届いているが、正しく処理されていない：通知自体はエンドポイントに到達しているものの、内容の検証や後続の処理でつまずき、意図した会員ステータスの更新や入金確認に反映されていないケース

いずれのパターンでも、事業者側からは「何かがうまくいっていない」という結果としてしか気づけないことが多く、会員ステータスが更新されていないのか、入金が確認できていないのかなど、原因の切り分けが必要になります。

よくある落とし穴｜Webhook失敗の主な原因

• エンドポイントの一時的なダウン・メンテナンス：自社サーバーの再起動やデプロイ作業のタイミングと重なり、通知を受け取れない状態になっている
• 応答（レスポンス）が正しく返せていない：通知を受け取った後、システム側の処理でエラーが発生し正常な応答を返せていない
• 検証情報の設定ミス：通知が本物のPAY.JPから送られたものかを確認するための値が、システム側で正しく設定・照合されていない
• アクセス集中による配信遅延：月末月初など決済処理が集中するタイミングでは、通知の到着までに数時間程度の遅延が生じる場合がある

なお、決済を実行するAPIリクエスト自体がエラーになるケース（APIキーの認証エラーなど）は、Webhookの失敗とは別の問題です。リクエストがエラーになった場合は、その時点でシステムにエラーが返ってきます。

「決済は処理されたのに通知だけが届かない」のか、「そもそもリクエストがエラーになっている」のかを最初に切り分けてください。APIキーの認証エラーについてはAPI認証エラーとは？で解説しています。

発生したときの対処法

Webhook失敗が疑われる場合は、次の順番で確認すると原因を切り分けやすくなります。

1. 管理画面の「イベント」で、PAY.JP側の処理を確認する：PAY.JPの管理画面にある「イベント」では、決済・入金などの処理結果の履歴を確認できます。ここに履歴があるのに自社システムに反映されていなければ、通知が届いていない、または届いても処理できていない可能性があります。詳しくは管理画面の「イベント」とはなんですか？を参照してください
2. PAY.JPの自動リトライを待つ：後述のとおりPAY.JPには配信失敗時に自動で再送信を行う仕組みがあるため、短時間の障害であれば再送で解消することがある
3. 開発担当者と連携してログを確認する：エンドポイント側のリクエストログ・エラーログを残していれば、それを開発担当者に確認してもらい、通知が届いていたか・どこでエラーになったかを切り分ける
4. 解消しない場合はサポートに問い合わせる：自社側の設定を確認しても解消しない場合は、PAY.JPヘルプからサポートに問い合わせる

再発を防ぐためにできること

• リクエスト・エラーログを残す運用を徹底する：PAY.JPのAPIドキュメント（Webhook）でも、通知を受け取った際のリクエストログ・エラーログの記録が強く推奨されています。ログがあれば「本当に届いていなかったのか」「届いていたのに処理でエラーになったのか」を後から切り分けやすくなります
• エンドポイントの死活監視を組み込む：PAY.JPのヘルプでは、Webhookの配信失敗を知らせる通知は案内されていません。そのため、自社サーバーが正常に稼働しているかを定期的に確認する仕組みを用意しておくと、通知を受け取れない状態に早く気づけます
• 決済代行会社ごとのリトライ仕様を把握しておく：再送の回数・期間は決済代行会社によって異なります。たとえばKOMOJUは、失敗した配信に対して最大25回・最長25日間かけて段階的に間隔を広げながら再送を試みる仕様です。後述のとおりPAY.JPはこれより短い期間で再送を終える仕様のため、障害発生時に気づいて対応できる猶予が短いことを踏まえておく必要があります
• 同じ通知が複数回届く前提で設計する：再送によって同じ内容の通知が重複して届く可能性があるため、Webhookとは？でも触れているとおり、処理済みかどうかを判定できる設計にしておくことが望まれます

PAY.JPのWebhook再送の仕様

PAY.JPは、イベントとWebhook（v2のドキュメント）によると、通知の配信に失敗した場合（200番台以外のステータスコードが返ってきた場合・10秒のタイムアウト・接続エラー時）、3分間隔で最大3回（合計9分程度）まで自動で再送する仕様になっています。なお、v1のAPIドキュメント（Webhook）では、再送の対象は「400番台・500番台のステータスコードが返ってきた場合」と記載されています。

前述のKOMOJUの最大25回・25日間という仕様と比べると短い期間で再送が終了するため、通知が届かない状態が続いていないか、比較的早いタイミングで気づける体制を整えておくことが重要です。

これから決済機能の導入を検討している方、Webhookまわりの運用について相談したい方は、PAY.JPのサービスページも確認してみてください。

まとめ

• Webhook失敗とは、通知が届かない、または届いても正しく処理されない状態で、エンドポイントの停止や応答エラー、検証設定ミスなどが原因になる
• 対処はまず管理画面の「イベント」確認、次に開発担当者と連携したログ確認が基本の流れ
• PAY.JPの自動再送は3分間隔・最大3回（合計9分程度）と短いため、ログの記録と死活監視で早く気づける体制が重要
• 決済導入・運用について相談したい方はPAY.JPのサービスページも確認してみてください