# webhookが一向に届かないとき

Source: https://help.didit.me/ja/integration/webhook-troubleshooting
Updated: 2026-10-12

配信ログ、イベント名、ファイアウォール、署名の順に確認します。Deliveriesタブを見ればDiditが送信したかがすぐわかり、問題を半分に絞り込めます。

まず送信先の**Deliveries**タブを確認してください。Diditが一度も配信を試みていなければ、購読設定か送信先の問題です。試みたのに失敗している場合は、レスポンスコードで原因がわかります。**404**は、そのURLで自社のルートに到達できなかったことを意味し、署名の不一致は誤ったバイト列でハッシュを計算していることを意味します。

## ステップ1：Diditは送信を試みたか

開発者、Webhookからエンドポイントを選び、配信一覧で各試行のリクエストと応答を確認します。修正後に再送してください。アプリケーション、環境、イベント購読、エンドポイントの有効状態を確認します。

![送信先ごとの配信ステータスを表示するDiditコンソールのwebhookページ](https://help.didit.me/screenshots/webhooks-light.webp)

*欠落したイベントと失敗しているエンドポイントを区別するために必要な情報はすべてこのページにあります。*

このひとつの確認だけで、問題を半分に絞り込めます。

- **試行ログがない** → その送信先向けのイベントが一度も生成されていません。ステップ2に進んでください。
- **試行ログがあり、失敗している** → Diditは送信し、あなたの側で拒否したか受信できなかったことになります。ステップ3に進んでください。
- **試行ログがあり、2xx** → 正常に配信されています。問題は配信ではなく、自社のハンドラー内にあります。

## ステップ2：試行ログがない場合

可能性が高い順に挙げます。

1. **そのイベントが購読されていない。** ワイルドカードは存在せず、すべてのイベントファミリーを明示的にリストアップする必要があります。存在しない名前（`session.status.updated`、`kyc.completed`など）を指定すると、何も届かないまま黙って終わります。[イベント一覧](https://help.didit.me/ja/integration/webhooks-basics)と照合してください。
2. **アプリケーションが違う。** 送信先はアプリケーションに属しています。セッションが送信先とは別のアプリケーションで動いている場合、イベントが届くことは決してありません。設定が正しく見えるのに動かない場合の、最もよくある原因です。
3. **実際には何も変わっていない。** webhookは変化があったときに発火します。動いていないセッションや、閾値を超える結果がなかったAML継続モニタリングの再スクリーニングは、正しくイベントを生成しません。
4. **待っているステータスがまだ発生していない。** In Progressのセッションはまだ完了していません。[セッションが終わらないとき](https://help.didit.me/ja/verification-sessions/session-not-finished)をご覧ください。

## ステップ3：配信が試みられて失敗した場合

**404**は、リクエストは届いたがそのルートが存在しなかったことを意味します。以下を確認してください。

- 末尾のスラッシュを含む正確なパス。`/hook`を`/hook/`にリダイレクトするフレームワークは、動作するはずのエンドポイントを404や本文の欠落に変えてしまうことがあります。
- URLが公開されているかどうか。インターネットから到達できないローカルやステージングのホストは、この形で失敗します。
- 自社アプリの手前にあるプロキシ、ロードバランサー、パスベースのルーターが、そのパスを別の場所に送っていないか。

**5xx**は、自社のハンドラーが例外を投げたことを意味します。パースする前に生の本文をログに残せば、実際に何を受信したかを確認できます。

**タイムアウト**は、応答が十分速くなかったことを意味します。まず2xxを返し、処理はその後に行ってください。

**何も起きない・接続拒否**は、自社のエッジがブロックしたことを意味します。Diditは静的IPの**18.203.201.92**から、`DiditWebhook/2.0`というユーザーエージェントで配信します。Cloudflareやデフォルト拒否のWAFの背後にいる場合は、受信ホスト名についてそのIPを許可してください。

## よくあるパターン：自動配信は404になるがResendは成功する

これはよく起きるので、名前を付けておく価値があります。自動配信は404で失敗するのに、同じイベントで**Resend**をクリックすると成功します。

この組み合わせは、ペイロードとエンドポイントの両方に問題がないことを意味します。つまり違いは内容ではなくタイミングやパスにあります。以下を確認してください。

- 元の配信の瞬間に**デプロイや再起動**が発生していなかったか。アプリが再び稼働状態になっているため、Resendは後で成功します。
- プラットフォームのタイムアウトを超えた**コールドスタート**。サーバーレスで最初の呼び出しが遅い場合によく見られます。
- 2回の試行の間で**パスベースのルーティングが変わった**、あるいは一部のリクエストにしか一致しないルールがあった。
- 手動の再送は単発で届いたために通過した、自社エッジでの**レート制限やボット対策**。

Deliveriesタブには両方の試行がタイムスタンプ付きで記録されているので、その時刻の自社のデプロイログやエラーログと突き合わせてください。

## 署名検証が失敗する

ほぼ次の3つのいずれかです。

1. **再シリアライズされたJSONでハッシュを計算している。** HMACは受信した**生の**リクエスト本文のバイト列そのものに対して計算してください。パースして再び文字列化すると空白やキーの順序が変わり、署名が一致しなくなります。多くのフレームワークでは、生の本文を得るために明示的な設定が必要です。
2. **シークレットが違う。** 署名用シークレットは**送信先ごと**に異なり、APIキーとは別物です。2つの送信先には2つの異なるシークレットがあります。
3. **エンコーディングの前提が違う。** シークレットをリテラル文字列として使うのか、デコードしてから使うのか不明な場合は推測せず、[署名検証のリファレンス](https://docs.didit.me/integration/webhooks#signature-verification)を正確に確認し、デバッグ中は生の本文をログに残して比較できるようにしてください。

> **Warning:** 署名の不一致を検証のスキップで「直す」ことは絶対にしないでください。検証されていないwebhookエンドポイントは、そのURLを見つけた誰からの偽の承認でも受け入れてしまい、デバッグ用の近道がアカウント乗っ取りの経路に変わってしまいます。

## 2回のリトライはキューではない

5xxまたは404の応答には約1分後、さらに4分後の2回再試行します。5秒のタイムアウトや接続失敗は自動再試行されません。修正後は配信一覧から再送できます。最終的な失敗ではアラートが表示されます。

整合性を取るための仕組みを用意してください。起動時に、確定ステータスを持っていないセッションについて判定エンドポイントをポーリングします。webhookは高速な経路として、ポーリングは保険として扱ってください。

## 検証を実行せずにテストする

[Video: APIキーの設定とWebhookのテスト - Didit Academy](https://www.youtube.com/watch?v=thOMIGbNLP0&t=140)

送信先ページの**テストイベントを送信**は、選んだ種類の完全な形のイベントを送信します - 承認、拒否、審査中、KYB、エンティティ、トランザクションなどです。実際のセッションがそれに依存する前に、自社のエンドポイント、署名チェック、ハンドラーが正しく動くことを確認するために使ってください。

サンドボックスはこのもう半分を担います。サンドボックスセッションは`"environment": "sandbox"`を持つ本物のwebhookを発行するため、経路全体を無料でエンドツーエンドに検証できます。[サンドボックスでのテスト](https://help.didit.me/ja/getting-started/sandbox-and-testing)をご覧ください。