壊れないeKYC APIの設計。状態機械とWebhook

Q: eKYCのAPI連携はなぜ非同期設計が必要なのですか？

本人確認の1件は申込→書類・生体の取得→自動判定→手動審査→確定と進み、途中離脱や審査待ちで日をまたぐことがあるためです。同期型の発想では審査待ちや期限切れなどの中間状態を表現できず破綻します。確認セッションの状態機械を中心に置き、POSTで作成・GETで照会・Webhookで結果通知という構成が基本形です。

Q: eKYCの状態機械にはどんな状態を定義すべきですか？

created（発行済み・未着手）、collecting（取得中）、processing（自動判定中）、manual_review（審査待ち）、approved（成立）、rejected（不成立）、expired（期限切れ）の7状態が基本です。approved・rejected・expiredは終端状態として書き換え不可とし、やり直しは新しいセッションの発行で行います。

Q: Webhookの重複や順序逆転にはどう対処すればよいですか？

重複・遅延・順序逆転は起きる前提で設計します。イベントIDで受信記録を持ち処理済みなら200を返す、イベントの順序番号やセッションの現在状態と突き合わせて古いイベントを捨てる、Webhookとは別にGET照会を保険として併設する、の3点が柱です。

Q: eKYCのWebhookに署名検証は必須ですか？

必須です。署名検証がなければapprovedを偽装したPOST一発で本人確認を突破される恐れがあります。署名対象はタイムスタンプ+生のリクエストボディとし、タイムスタンプの許容差でリプレイを弾き、鍵ローテーションと検証失敗時のアラートまで設計します。

Q: 冪等性キー（Idempotency-Key）とは何ですか？

同じリクエストの二重実行を防ぐ仕組みです。クライアントがリクエストごとに一意のキーを付け、サーバーは同じキーのリクエストに最初の実行結果をそのまま返します。eKYCでは通信断でのリトライ時にセッションの二重作成・二重課金を防ぎます。

Q: 複数のeKYCベンダーを併用する場合の設計はどうすべきですか？

ベンダーAPIを直接呼ばず、自社ドメインの共通インターフェースを1枚挟み、各ベンダーをその実装として差し込みます。どの方式でのapprovedかという確認の強さまで正規化して記録することが重要で、この抽象化があると制度変更時の改修を差し込み実装の範囲に閉じ込められます。

eKYC（オンライン本人確認）をシステムに組み込むとき、画面や判定エンジンよりも先に品質が問われるのが、API・Webhook連携の設計です。本記事は、本人確認APIを自社で設計する場合と、eKYCベンダーのAPIを受ける場合の両方に共通する「壊れない設計パターン」を整理します。実装者だけでなく、発注者・事業会社の開発責任者が「ベンダーの仕様書のどこを見れば連携品質を判断できるか」まで分かる構成にしています。確認日: 2026年8月23日。

この記事の要点

本人確認は数秒で終わらない非同期プロセスです。設計の中心は「確認セッション」の状態機械であり、APIはその状態を進める・読むための入り口にすぎません

Webhookの配送保証は「少なくとも1回（at-least-once）」が原則です。重複・遅延・順序逆転を受信側が吸収できて初めて連携が成立します

冪等性キーと署名検証は付加機能ではありません。課金の二重計上と、なりすまし通知による本人確認の突破という実害を防ぐ最低ラインです

複数の確認方式（JPKI・顔照合・OCR）を扱うなら、共通インターフェースを1枚挟むことで制度変更・ベンダー乗り換えの改修規模が桁で変わります

なぜリクエスト/レスポンス型では破綻するのか

eKYCの1件は、「申込→書類・生体情報の取得→自動判定→（必要に応じて）手動審査→確定」という流れをたどります。ユーザーが途中で離脱することもあれば、手動審査の待ち時間で日をまたぐこともある、本質的に非同期のプロセスです。

これを通常のWeb APIと同じ「リクエストを送れば結果が返る」という発想で設計すると、途中離脱・審査待ち・期限切れといった中間状態の表現に必ず無理が生じます。API設計に着手する前に、まず確認セッションの状態機械（ステートマシン）を固定するのが正しい順序です。

確認セッションの状態遷移表

状態	意味	遷移先
created	セッション発行済み。ユーザー未着手	collecting / expired
collecting	書類・生体を取得中	processing / expired
processing	自動判定の実行中	approved / rejected / manual_review
manual_review	人の審査待ち	approved / rejected
approved	確認成立	(終端)
rejected	確認不成立	(終端)
expired	期限切れ・離脱	(終端)

この状態機械を運用するルールは3つです。

許可した遷移だけを通す。表にない遷移（approvedからcollectingに戻る、など）はエラーとして拒否します。想定外の遷移を許すコードがバグの温床になります
終端状態は不変にする。approved・rejected・expiredに到達したセッションは書き換えず、やり直しが必要なら新しいセッションを発行します
すべての遷移を監査ログに残す。「いつ・何がきっかけで・どの入力に基づいて」遷移したかを記録します。犯罪収益移転防止法が求める確認記録の7年保存は、この遷移ログが土台になります。何を証跡として残すかはエビデンス設計の論点です

APIはこの状態機械の写像として設計します。POSTでセッションを作成し、GETで現在状態を照会し、結果はWebhookで通知する。GETは何度呼んでも同じ結果を返す（読み取りは常に冪等）ため、クライアント側のリトライが安全になります。

冪等性キー: 二重実行を仕組みで止める

ネットワークは必ず切れます。クライアントが「作成リクエストは送れたが応答を受け取れなかった」とき、取れる手段はリトライしかありません。ここで何も対策していないと、確認セッションが二重に作られ、従量課金のeKYCサービスであれば二重に課金されます。

対策の定番が冪等性キー（Idempotency-Key）です。クライアントはリクエストごとに一意のキーを付与し、サーバーは「同じキーのリクエストには、最初の実行結果をそのまま返す」ように振る舞います。冪等性の概念はRFC 9110で定義され、ヘッダーの標準化はIETFのIdempotency-Keyドラフトで進められています。

設計時に決めるべきポイントは3つです。

スコープ: キーはエンドポイント×クライアント単位で管理し、別のAPIとキー空間を衝突させない
TTL: キーの保持期間は、リトライが起こりうる時間（数時間〜24時間程度)をカバーする
同一キー・異なる内容の扱い: 同じキーで異なるペイロードが届いたら、黙って上書きせずエラーで拒否する。クライアント側のバグを早期に発見できます

Webhookの受信設計: 「少なくとも1回」を受け切る

判定完了の通知にはWebhookを使うのが標準ですが、Webhookの配送保証は原理的に「少なくとも1回（at-least-once）」です。「ちょうど1回だけ届く」ことを前提にした受信処理は、いつか必ず壊れます。受信側が吸収すべき事象は4つあります。

起きること	対策
重複する	同じイベントが2回届く前提で、イベントIDの受信記録を持ち、処理済みなら黙って200を返す
遅れる	数分〜数時間の遅延がありうる。Webhookを唯一の情報源にせず、GETでの照会（ポーリング）を保険として併設する
順序が逆転する	「審査中」より「承認」が先に届きうる。イベントの順序番号やセッションの現在状態と突き合わせ、古いイベントは捨てる
失敗する	受信側の障害中の通知は再送頼みになる。再送ポリシー（回数・間隔）と、再送が尽きた後の回収手段（照会API）を確認する

受信処理の基本形は「即座に200を返してキューに積み、非同期で処理する」です。Webhookハンドラの中で重い処理や外部API呼び出しを行うと、タイムアウトが送信側の再送を誘発し、負荷が雪だるま式に膨らみます。

署名検証: なりすまし通知で本人確認を突破させない

WebhookのエンドポイントはインターネットからPOSTできるURLです。署名検証を実装していなければ、「approved」を偽装したリクエスト一発で本人確認を突破される可能性があります。これはeKYCという仕組みの根幹に関わるため、検証は省略できません。要点は4つです。

**署名対象は「タイムスタンプ+生のリクエストボディ」**とします。パース後のJSONから再構築すると、空白や数値表現の差で検証が壊れます
タイムスタンプの許容差（例: 5分）を設け、古い署名の再送（リプレイ攻撃）を弾きます。イベントIDの受信記録が、許容差内のリプレイによる二重処理を防ぐ第二の壁になります
署名鍵のローテーションに対応します。新旧2鍵を並行して受け入れる期間を設ける設計です
検証失敗はアラート対象にします。攻撃の兆候か鍵設定ミスかのどちらかであり、どちらも放置できません

なお、署名や証明書を「どの順序で検証するか」はJPKI連携でも同型の論点があります。署名検証の正しい順序も併せて参照してください。

複数プロバイダ時代の構え: 共通インターフェース

JPKI、顔照合、OCR、外部eKYC SaaSと、本人確認の手段は増え続けます。プロバイダのAPIを業務コードから直接呼ぶと、アプリケーションがベンダー固有の仕様に汚染され、乗り換えも並行利用もできなくなります。

対策は古典的ですが有効で、自社ドメインの共通インターフェース（確認の開始・状態取得・結果の正規化）を1枚挟み、各プロバイダをその実装として差し込む構成にします。正規化で最も重要なのは結果の意味論を揃えることです。「あるプロバイダのapprovedと、別のプロバイダのapprovedは同じ強さの本人確認か」を、確認方式（JPKIか顔照合か）と一緒に記録します。

2027年に施行される制度改正では、eKYCの許容方式そのものが変わります（2027年施行後のeKYC方式一覧）。この種の制度変更が来たとき、抽象化レイヤーの有無で改修規模は桁で変わります。自社開発か外部サービス利用かの判断はeKYCの内製・外注コスト比較も参考になります。

発注者向け: ベンダーAPI仕様書のチェックリスト

eKYCベンダーを選定する立場であれば、API仕様書・Webhook仕様書で次の項目が文書化されているかを確認してください。ここが曖昧なベンダーとの連携は、開発フェーズで手戻りが発生しがちです。

確認セッションの状態一覧と遷移図が定義されているか
終端状態からのやり直し手順（新規セッション発行）が明記されているか
冪等性キー（またはそれに相当する二重実行防止策）に対応しているか
Webhookの署名方式・検証手順が文書化されているか
署名のタイムスタンプ許容差とリプレイ対策の記載があるか
Webhookの再送ポリシー（回数・間隔・打ち切り条件）が明記されているか
再送が尽きた後に結果を回収できる照会APIがあるか
署名鍵のローテーション手順（新旧並行期間）が用意されているか

この観点は、eKYCサービスの選び方20項目のAPI・連携仕様の項目とセットで使えます。

まとめ

eKYCは非同期プロセスであり、設計の中心は確認セッションの状態機械です。許可した遷移だけを通し、終端状態は不変にし、全遷移を監査ログに残します
書き込み系APIは冪等性キーで二重実行を防ぎます。同一キー・異なる内容のリクエストは上書きせずエラーで拒否します
Webhookは「少なくとも1回」配送が前提です。重複・遅延・順序逆転・欠落の4つを受信側で吸収し、照会APIを保険として併設します
Webhook署名は「タイムスタンプ+生ボディ」で検証し、リプレイ対策と鍵ローテーションまで設計します
複数プロバイダは共通インターフェースの背後に置き、制度変更・乗り換えに備えます
ベンダー選定時は、状態遷移・冪等性・署名・再送の文書化レベルで連携品質を見極められます

全体像をつかみたい方はeKYC完全マップ2026を、シリーズの読む順はeKYC・本人確認記事の全体目次を参照してください。

よくある質問

Q. eKYCのAPI連携はなぜ非同期設計が必要なのですか？

本人確認の1件は「申込→書類・生体の取得→自動判定→手動審査→確定」と進み、ユーザーの途中離脱や審査待ちで日をまたぐことがあるためです。リクエストを送れば即座に結果が返る同期型の発想で作ると、審査待ちや期限切れといった中間状態を表現できず破綻します。確認セッションの状態機械を中心に置き、POSTで作成・GETで照会・Webhookで結果通知という構成が基本形です。

Q. eKYCの状態機械にはどんな状態を定義すべきですか？

created（発行済み・未着手）、collecting（書類・生体の取得中）、processing（自動判定中）、manual_review（人の審査待ち）、approved（確認成立）、rejected（確認不成立）、expired（期限切れ・離脱）の7状態が基本です。approved・rejected・expiredは終端状態として書き換え不可とし、やり直しは新しいセッションの発行で行います。

Q. Webhookの重複や順序逆転にはどう対処すればよいですか？

Webhookは「少なくとも1回」配送が原則のため、重複・遅延・順序逆転は起きる前提で受信側を設計します。イベントIDで受信記録を持ち処理済みなら200を返す（重複対策）、イベントの順序番号やセッションの現在状態と突き合わせて古いイベントを捨てる（順序対策）、Webhookとは別にGET照会を保険として併設する（遅延・欠落対策）の3点が柱です。

Q. eKYCのWebhookに署名検証は必須ですか？

必須です。Webhookのエンドポイントは外部から叩けるURLであり、署名検証がなければ「approved」を偽装したPOST一発で本人確認を突破される恐れがあります。署名対象はタイムスタンプ+生のリクエストボディとし、タイムスタンプの許容差でリプレイを弾き、鍵ローテーションと検証失敗時のアラートまで含めて設計します。

Q. 冪等性キー（Idempotency-Key）とは何ですか？

同じリクエストが二重に実行されることを防ぐ仕組みです。クライアントがリクエストごとに一意のキーを付け、サーバーは同じキーのリクエストに最初の実行結果をそのまま返します。eKYCでは通信断でのリトライ時にセッションの二重作成・二重課金を防ぎます。冪等性の概念はRFC 9110で定義され、ヘッダーの標準化がIETFで進められています。

Q. 複数のeKYCベンダーを併用する場合の設計はどうすべきですか？

ベンダーAPIを業務コードから直接呼ばず、自社ドメインの共通インターフェース（確認の開始・状態取得・結果の正規化）を1枚挟み、各ベンダーをその実装として差し込みます。正規化では「どの方式（JPKI・顔照合等）でのapprovedか」という確認の強さまで揃えて記録することが重要です。この抽象化があると、2027年の方式移行のような制度変更でも改修を差し込み実装の範囲に閉じ込められます。

主な参考資料: RFC 9110: HTTP Semantics（冪等性の定義）、IETF draft: The Idempotency-Key HTTP Header Field、デジタル庁デジタル認証サービス実装ガイド

TodoONada株式会社は、マイナンバーカード認証（JPKI・eKYC）を組み込んだWebサービス・スマホアプリの受託開発を行っています。本記事で扱った状態機械・Webhook受信・冪等性の設計は、当社が本人確認基盤を構築する際の標準的な進め方です。方式選定（JPKI・IC読取り・画像方式）から開発・運用まで、またデジタル庁「デジタル認証アプリ」の利用申請・審査対応の伴走支援まで対応します。料金の目安は認証機能組込みプラン150万円〜、認証込みアプリ開発プラン400万円〜です。既存基盤のアーキテクチャレビューのご相談も、マイナンバーシステム導入支援からお寄せください。

この記事に関連するサービス

TodoONada株式会社では、マイナンバーカード認証を組み込んだシステム開発を行っています。

マイナンバーシステム導入支援 — JPKI・eKYC対応の本人確認をワンストップで

導入・開発のご相談はお問い合わせからお気軽にどうぞ。検討段階のご相談も歓迎です。