APIウェブフックの検証

はじめに

ウェブフックはAPIの拡張機能です。お客様のコードがAPIプラットフォームからデータをリクエストする代わりに、Vonageはお客様のアプリケーションへのウェブリクエストを介してお客様にデータを送信します。Verify API webhook はお客様のリクエストのステータスアップデートを受信し、以前の API 呼び出しの結果となります。

ウェブフックの受信

Vonage サーバーが Webhook を介してお客様のアプリケーションにデータを送信できるようにするには、HTTP リクエストを受信する Web サーバーをセットアップする必要があります。また、各Webhookにデータを送信できるように、Webサーバー上で各WebhookのURLを指定する必要があります。

Verifyウェブフックの使用を開始する：

Vonageアカウントを作成する。
Vonageから送信または要求された情報を処理するスクリプトを記述します。あなたのサーバーは 200 または 204 HTTPレスポンスは 2xx コードは、Vonageサーバーにコールバック配信を再試行させます。
スクリプトをサーバーにデプロイして公開します。ローカルで開発する場合はングロク.
Verify ウェブフック・エンドポイントの設定.
アクションを起こす SMS認証リクエストの送信)がそのウェブフックをトリガーする。

その後、リクエストに関する情報がWebhookエンドポイントに送信されます。

VerifyウェブフックURLの設定

Verify API は Status webhook をサポートしています。アプリケーション設定開発者ダッシュボードの

Webhooks can be configured on the customer dashboard

これは、Verifyリクエストのステータス更新（例えば、進行状況や完了イベント）を送信するために使用されます。

ローカルでウェブフックをテストする

ローカルで実行されているアプリケーションでWebhookが正しく機能することをテストするには、Vonageとアプリケーションの間に安全なトンネルを作成する必要があります。次のようなセキュアトンネルアプリケーションでこれを行うことができます。ングロク.参照 Ngrokを使ったテストをご覧ください。

署名入りウェブフック

Verify webhookはデフォルトで署名されています。署名された Webhook を使用すると、アプリケーションはリクエストが Vonage からのものであり、そのペイロードが転送中に改ざんされていないことを確認できます。リクエストを受信すると、受信する Webhook は、お客様の署名シークレットで署名された JWT トークンを認証ヘッダーに含めます。

署名付きWebhookのデコードに関する詳細は、以下を参照してください。これ.

コールバックの種類

イベント・コールバック

受信イベントウェブフック。これは、リクエストの最終結果を status フィールドにいる：

completed - リクエストは完了し、ユーザーのVerifyに成功した。
blocked - 速度規則によりリクエストがブロックされたか、提供された番号がVOIPである。
failed - の場合、指定された番号が有効な番号でなかったため、リクエストは失敗した。
expired - リクエストは所定の時間内に完了しなかった。
user_rejected - ユーザが不正なピンを入力した。
cancelled - の場合、ユーザーは認証プロセスを完了する前にリクエストをキャンセルした。
action_pending - ユーザが認証手続きを開始するためのアクションを何も行っていない場合。たとえば check_url ユーザは、サイレント認証を開始するために、まだ何もしていない。

{
   "request_id": "c11236f4-00bf-4b89-84ba-88b25df97315",
   "triggered_at": "2020-01-01T14:00:00.000Z",
   "type": "event",
   "channel": "sms",
   "status": "completed",
   "finalized_at": "2020-01-01T14:00:00.000Z",
   "client_ref": "my-personal-ref"
}

サイレント認証

その一環としてサイレント認証リクエストするとイベントコールバックをウェブフックに追加します：

{
   "request_id": "c11236f4-00bf-4b89-84ba-88b25df97315",
   "triggered_at": "2020-01-01T14:00:00.000Z",
   "type": "event",
   "channel": "silent_auth",
   "status": "action_pending",
   "action": [
      {
         "type": "check",
         "check_url": "https://eu.api.silent.auth/phone_check/v0.1/checks/:request_id/redirect"
      }
   ]
}

サマリー・コールバック

Summaryコールバックは、特定のリクエストの受信ステータスの更新を含む。下の例でわかるように、Statusフィールドは2つあります。1つはリクエスト全体のステータスで、もう1つはワークフローで使われた各チャネルの結果を示しています。

リクエストに対して、6つの異なるStatus値が表示されます：

completed - リクエストは完了し、ユーザーのVerifyに成功した。
failed - 指定された番号が有効な番号でないか、モバイルIPでないため、リクエストは失敗した。
expired - リクエストは所定の時間内に完了しなかった。
user_rejected - ユーザが間違ったピンを3回入力したため、ワークフローが終了した。
blocked - 速度規則によりリクエストがブロックされたか、提供された番号がVOIPである。
cancelled - の場合、ユーザーは認証プロセスを完了する前にリクエストをキャンセルした。

ワークフローでは、APIを使用する際に表示される7つの異なるStatus値がある：

unused - リクエストはワークフローの前のチャネルによって変換されたので、チャネルは使用されなかった。
completed - チャンネルが使用され、検証に成功した。
failed - ワークフローで定義されたチャネルが、指定された番号が有効な番号でない、またはモバイルIPでない、あるいはユーザーがいる国がVerifyの対象外であるなどの理由で失敗した。
expired - ワークフローで定義された任意のチャネルは、OTPが指定された制限時間内に入力されなかったため、失効しました。
blocked - SMS/音声チャネルが速度規則によりブロックされました。
user_rejected - ユーザーが誤ったピンを3回入力したため、使用したチャンネルのワークフローが終了した。
cancelled- ワークフローで定義された特定のチャネルの認証プロセスが、進行中にキャンセルされた。

この例は、完了した検証リクエストの更新を示しています。最初のチャネルは SMS を使用しようとしたが、リクエストは期限切れとなった。次にWhatsAppが使用され、ユーザーの認証に成功した。音声チャネルは試行されなかったため、ステータスは次のように表示される。 unused.

{
   "request_id": "c11236f4-00bf-4b89-84ba-88b25df97315",
   "submitted_at": "2020-01-01T14:00:00.000Z",
   "status": "completed",
   "type": "summary",
   "channel_timeout": 300,
   "workflow": [
      {
         "channel": "sms",
         "initiated_at": "2020-01-01T14:00:00.000Z",
         "status": "expired"
      },
      {
         "channel": "whatsapp",
         "initiated_at": "2020-01-01T14:02:00.000Z",
         "status": "completed"
      },
      {
         "channel": "voice",
         "initiated_at": "2020-01-01T15:05:00.000Z",
         "status": "unused"
      }
   ],
   "client_ref": "my-personal-ref"
}

サイレント認証リクエストを完了するには check_url を作成し、それをクライアントに渡して認証してもらう。