المدونة · 25 يونيو 2026

Webhookの冪等性：信頼性の高い本人確認ワークフローを構築する

Webhookの冪等性は、本人確認ワークフローの信頼性と堅牢性を確保し、重複処理を防ぎ、ネットワークの問題や再試行に直面してもデータの一貫性を維持するために不可欠です。

بواسطة Didit25 يونيو 2026تحديث 30 يونيو 2026

Webhookの冪等性とは、再試行やネットワークの不具合などによりWebhookが複数回処理されたとしても、一度だけ処理された場合と同じ結果を生み出すことを保証し、重複した本人確認や矛盾したユーザー状態などの意図しない副作用を防ぐものです。

本人確認においてWebhookの冪等性が重要な理由

本人確認プロセスは、その性質上、機密性の高いデータを含み、多くの場合、アカウントのアクティベーション、リスクスコアリング、取引承認などの後続のアクションをトリガーします。このような機密性の高いワークフローでは、重複処理の結果は、軽微な非効率性から重大な金銭的損失やコンプライアンス違反にまで及ぶ可能性があります。受信側の一時的なネットワークエラーによりuser_verified Webhookが2回送信され、2つの個別のアカウントアクティベーションが発生したり、さらに悪いことに、2つの同一の本人確認が開始され、その費用が支払われたりするシナリオを想像してみてください。

ここでWebhookの冪等性が不可欠になります。Webhookハンドラーを冪等に設計することで、Webhookが複数回受信および処理されたとしても、基盤となるシステムの状態は意図どおりに1回だけ変更されることを保証します。

冪等性の中核概念

数学およびコンピューターサイエンスにおいて、ある操作が冪等であるとは、それを複数回適用しても、一度適用した場合と同じ結果が得られることを意味します。Webhookの場合、これは次のことを意味します。

重複する副作用がない：支払いは1回だけ処理され、ユーザーのステータスは1回だけ更新され、本人確認は1回だけ開始されます。
一貫した状態：メッセージが再配信されても、システムの状態は一貫性を保ちます。
障害に対する回復力：システムは、データを破損したり、冗長なアクションを実行したりすることなく、ネットワークの問題、タイムアウト、再試行に耐えることができます。

Webhookの冪等性の実装

Webhookの冪等性を実装する最も一般的なアプローチは、受信する各Webhookに冪等性キーと呼ばれる一意の識別子を使用することです。

1. 冪等性キー

Webhookが送信されると、送信者（例：Didit）はリクエストヘッダーまたはボディに一意の識別子を含めます。これはWebhook-IdまたはX-Didit-Request-Idである可能性があります。このキーは、特定のWebhookイベントを配信するすべての試行に対して一意である必要があります。

2. キーの保存と確認

Webhookを受信すると、ハンドラーは次の手順を実行する必要があります。

冪等性キーを抽出する：受信リクエストから一意の識別子を取得します。
永続ストアを確認する：データベース（例：Redis、PostgreSQL、DynamoDB）にクエリを実行して、この冪等性キーが以前に処理されたことがあるかどうかを確認します。このストアは、高可用性で高速である必要があります。
条件付き処理：

キーが見つかった場合（Webhookが以前に処理されたことを意味します）、コアロジックを再実行せずにすぐに成功応答（例：HTTP 200 OK）を返します。該当する場合は、以前の成功した処理の結果を返すこともできます。
キーが見つからない場合、Webhookのペイロードの処理に進みます。この処理の一部として、冪等性キーを永続ストアに保存し、処理済みとしてマークします。このステップは、コアロジックとアトミックであるか、競合状態を防ぐために慎重に処理する必要があります。

冪等性ロジックの例（擬似コード）：

def webhook_handler(request):
    idempotency_key = request.headers.get('X-Didit-Request-Id')
    if not idempotency_key:
        return HttpResponseBadRequest('Missing X-Didit-Request-Id header')

    # Check if this key has been processed
    if is_key_processed(idempotency_key):
        # Optionally, retrieve and return the previous result
        return HttpResponse(status=200, content='Already processed')

    try:
        # Process the webhook payload (e.g., update user status, trigger KYC (Know Your Customer))
        process_identity_event(request.json)
        
        # Mark the key as processed *after* successful processing
        mark_key_as_processed(idempotency_key)
        return HttpResponse(status=200, content='Processed successfully')
    except Exception as e:
        # Handle errors, potentially log and retry later
        return HttpResponseServerError(f'Error processing webhook: {e}')

冪等性キーの保存に関する考慮事項：

有効期限：冪等性キーは永久に存在する必要はありません。一定期間（例：再試行ポリシーに応じて24時間から数日間）経過後、安全に期限切れにすることができます。
アトミック性：キーの確認と保存（または処理中としてマークする）は、同じキーに対する2つの同時リクエストが両方ともコアロジックの処理に進むという競合状態を防ぐために、理想的にはアトミックである必要があります。
分散システム：分散環境では、Webhookハンドラーのすべてのインスタンスが同じ冪等性ストアを共有することを保証することが重要です。

Diditの本人確認および不正防止インフラストラクチャにおけるWebhook

Diditのインフラストラクチャは、本人確認（ユーザー確認/KYC、企業確認/KYB）および不正チェック（取引監視、ウォレットスクリーニング/KYT）の結果をシステムに伝えるためにWebhookに大きく依存しています。たとえば、ユーザー確認チェックが完了すると、Diditは設定されたエンドポイントにWebhookをディスパッチし、結果（approved、rejected、pending）を通知します。

これらのイベントの重要性（ユーザーがオンボーディングできるか、企業が取引できるか、支払いが安全であるか）を考慮すると、システムがこれらの更新を確実に1回だけ処理することを保証することが最も重要です。DiditのWebhookがネットワークの混雑やサーバーの一時的な問題により再配信されたとしても、アプリケーションがそれを単一のイベントとして正しく解釈し、次のような重複したアクションを防ぐために、Webhookの冪等性を実装することは、あなたの側で重要です。

ユーザーのアカウントを誤って2回アクティブ化する。
冗長な内部通知やワークフローをトリガーする。
システムが最初の試行が失敗したと誤解した場合に、チェックを再開することで不必要なコストを発生させる。

DiditのWebhookヘッダーで提供される冪等性キーを活用することで、データの整合性を維持し、リソースの使用を最適化する、真に回復力のある信頼性の高い本人確認ワークフローを構築できます。

主なポイント

Webhookの冪等性は、Webhookの繰り返し処理が、一度処理した場合と同じ効果を持つことを保証します。
重複したアクションを防ぎ、データの一貫性を維持するために、信頼性の高い本人確認ワークフローに不可欠です。
冪等性キー（送信者から提供される一意の識別子）は、冪等性を実装するための基本です。
Webhookハンドラーは、コアロジックを処理する前に、これらのキーを永続的な共有ストアに確認して保存する必要があります。
冪等性を実装することで、データを破損することなく、ネットワークの問題、再試行、システム障害から保護されます。
DiditのWebhookには、システムとの信頼性の高い統合を容易にするための冪等性キーが含まれています。

よくある質問

Q: Webhookの冪等性を実装しないとどうなりますか？

A: 冪等性がないと、システムは同じWebhookを複数回処理する可能性があり、特にネットワークの問題や再試行中に、重複したアクション、矛盾したデータ、潜在的なエラーにつながる可能性があります。

Q: Webhookペイロードを冪等性キーとして使用できますか？

A: 技術的には可能ですが（例：ペイロードをハッシュ化する）、Webhook送信者から提供される専用の一意の冪等性キーに依存する方が一般的です。これにより、ペイロードの軽微で重要でない部分が変更されたり、ペイロードが大きすぎたりしても、一貫性が保証されます。

Q: 冪等性キーはどのくらいの期間保存する必要がありますか？

A: 保存期間は、Webhookの再試行ポリシーによって異なります。一般的な慣行は、ほとんどの再試行期間をカバーするために24〜72時間保存することです。この期間が過ぎると、古いキーは安全に期限切れにすることができます。

Q: DiditはWebhookを送信する際に、その側で冪等性を処理しますか？

A: Diditは、各イベントに一意の識別子があることを保証し、当社のシステムはWebhook配信を再試行するように設計されています。これらの再試行を正しく管理し、あなたの側での重複処理を防ぐために、ハンドラーに冪等性を実装するのは、受信者としてのあなたの責任です。

信頼性の高いシステムを構築するには、潜在的な障害モードに細心の注意を払う必要があります。Webhookの冪等性を取り入れることで、本人確認および不正防止ワークフローが信頼性が高く、回復力のあるものになることを保証できます。Diditは、本人確認と不正防止のためのインフラストラクチャを提供し、1,000以上のデータソースとモジュールのオープンマーケットプレイスを備えた1つのAPIを提供します。最低料金なしの従量課金制の公開価格には、毎月500回の無料チェックが含まれており、完全な本人確認は0.30ドルから開始できます。5分で統合し、自信を持って構築してください。

Diditを始めましょう

Diditは、本人確認と不正防止のためのインフラストラクチャです。1つのAPI、公開された従量課金制の価格設定、毎月500回の無料検証を提供します。ユーザー確認をフローに追加し、5分で統合できます。

ユーザー確認 — 仕組みと費用をご覧ください。
ドキュメントを読む — APIリファレンスと統合ガイド。
無料で始める — 毎月500回の検証、クレジットカードは不要です。