メインコンテンツへスキップ

Webhook

本ドキュメントのGetProcessに関する記事では、エンドポイントを呼び出すことでプロセスのステータスを取得する方法について説明しています。この方法では、作成されたプロセスに関する情報を受け取るためにポーリングが行われます。つまり、同じプロセスについて最新のステータスを取得するために、エンドポイントを複数回呼び出すことができます。

Webhookを使用すると、プロセスのステータスが変化するたびに特定のエンドポイントに通知することができます。

Webhookとは?​

Webhookとは、システム間の非同期連携を実現するシステム通知サービスであり、あるシステムがトリガーを介して別のシステムに通知を行う仕組みです。これにより、更新状況を確認するために継続的にポーリングを行う必要なく、システムを最新の情報に保つことができます。

Webhookの設定方法​

Webhookを設定するには、以下の情報が必要です。

  • 通知URL: ステータス更新の通知にUnicoが使用するエンドポイントです。
  • 認証タイプ: エンドポイントの呼び出しを認証する方法です。以下のオプションが利用可能です。
    • OAuth2;
    • Basic Authorization;
    • APIキー;
    • 認証なし。
  • OAuth2の場合、以下の情報を提供する必要があります。
    • Webhookのendpoint;
    • OAuth2プロバイダーのURL;
    • OAuth2プロバイダーのClientId;
    • OAuth2プロバイダーのSecret。
  • Basic Authorizationの場合、user:passの形式で送信する必要があります。
  • APIキーの場合、2つの形式が可能です。
    • 特定のヘッダー名を指定したい場合はheader:value;
    • 目的のヘッダーがAuthorizationの場合はvalue。
  • リトライ設定: エンドポイント呼び出しに失敗した場合の試行回数を示します。
    • 最大試行回数;
    • 試行間隔(秒単位);
    • レート制限: 同時送信の最大数(最大:500);
    • タイムアウト: エンドポイントのレスポンスを待つ最大時間(秒単位)。
  • 通知するステータス: 通知を受け取りたい特定のステータスを購読できます。これには以下が含まれます。
    • approved:取引が承認された;
    • processing:取引を処理中;
    • inconclusive:確定的な検証を実行できなかった;
    • shared:取引が共有され、送信待ちの状態;
    • skipped:フロー内で生体認証キャプチャがスキップされた;
    • unknown-share:購入に心当たりがないとカード保有者がマークした;
    • absent-holder:カード保有者がキャプチャを行うために不在である;
    • expired:定められた時間内にキャプチャが完了せず、取引が期限切れになった。
認証について

APIはBasic AuthenticationやAPIキーなどの認証方法で保護できます。追加の保護として、アクセスを許可する有効なIPのリストを定義することもできます。

カード非提示認証との連携​

プラットフォーム上でWebhookを設定すると、これらの更新を受け取るためにお客様が開発したAPIのエンドポイントに送信される通知を通じて、プロセスに関する情報を受け取ることができます。

プラットフォームからAPIに送信される情報には、以下が含まれます。

  • ID:取引ID;
  • Status:取引ステータス;
  • HasIdentityChanged:取引内で本人情報の変更が発生したかどうか(任意)。
メモ

Webhookの設定を通じて、クライアントが通知を受け取りたいステータスを選択できることに注意してください。この情報を送信した後、期待されるレスポンスは同期的である必要があります。

リクエスト​

リクエストはREST APIに対するPOSTメソッドである必要があり、これにより情報の送信がより簡単かつ安全になります。すべてのフィールドは必須である必要があります。リクエストボディには、以下の例のように取引IDとステータスを含める必要があります。

{
  "id": "8263a268-5388-492a-bca2-28e1ff4a69f0",
  "status": "approved",
  "hasIdentityChanged": false
}

レスポンス​

レスポンスは同期的である必要があります。リクエストが成功した場合のステータスは200から299の範囲である必要があります。それ以外のステータスはすべて失敗とみなされ、カード非提示認証は2xxのレスポンスを受け取るか最大試行回数に達するまで、追加の通知試行を行います(試行間隔は指数バックオフに従います)。

レスポンスステータス​

現在、一連のステータスを用意していますが、このセットは将来変更される可能性があります。そのため、クライアントが関心を持つステータスを設定可能にしておくことを推奨します。例えば、キャプチャが正常に完了するたびにアクションを実行したい場合、現時点ではこれは"processing"のステータスで発生します。ただし、これは将来変更される可能性があるため、キャプチャの成功を示すステータスをシステム内で設定可能にしておくことを推奨します。そうすれば、将来"captured"というステータスに変更された場合でも容易に対応できます。

さらに、特定のステータスに対して特定のアクションを用意し、認識できないステータスの場合には一般的なアクションを用意することを推奨します(例えば、"processing"と"approved"以外のものはすべて確定的でないとみなす)。これは、将来新しいステータスが登場する可能性があり、それによってWebhookが機能しなくなることは想定されていないため重要です。

重要な考慮事項​

カード非提示認証がステータス変更を通知するために使用するAPIを開発する際は、以下の点に注意してください。

レート制限 — 多数の取引が発生する状況でリソースの過負荷を避けるため、エンドポイントを呼び出せる回数の上限を指定することができます。

エラー率 — エラー率([200, 299]の範囲外のレスポンス)は常に低く保つ必要があります。そうでない場合、Webhookのスループットは自動的に低下し、この低下がリトライの仕組みと組み合わさることで、新しいWebhookの実行時間が増加する可能性があります。

冪等性 — 現在のWebhookの実装は少なくとも1回の配信を保証しているため、同じステータスが複数回通知される場合があります。そのため、エンドポイントの実装は冪等な方法で行う必要があります。

フォールバック — Webhookサービスが利用できない場合に備え、定められたレスポンス時間内で引き続き取引ステータスを取得できるよう、フォールバック手段を用意しておくことを推奨します。エンドポイントの照会については、本ドキュメントのAPIリファレンスセクションで説明されています。

最終更新 に