APIウェブフックの検証

はじめに

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

ウェブフックの受信

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

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

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

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

VerifyウェブフックURLの設定

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

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

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

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

署名入りウェブフック

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

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

コールバックの種類

Verifyは、Webhook URLに対して2種類のコールバックを送信します：

• イベントのコールバック ("type": "event") — ワークフロー内の各チャネル試行ごとに送信されます。デフォルトでイベントコールバックを送信する「サイレント認証」を除き、Accountレベルの権限が必要です。
• サマリーコールバック ("type": "summary") — ワークフロー全体が完了した時点で、リクエストごとに1回送信されます。

イベント・コールバック

Verifyワークフロー内の各チャネルへの試行ごとに送信される、インバウンドイベントのWebhookです。イベントコールバックは、SMS、音声、WhatsApp、RCS、Eメール、サイレント認証、およびサイレント認証（アドバンスト）で利用可能です。

イベントコールバックは、アカウントレベルの機能設定によって有効化されます。サイレント認証では、この機能設定の有無にかかわらず、イベントコールバックが生成され続けます。その他のすべてのチャネルでは、アカウントレベルの機能設定を有効にする必要があります。アカウントでイベントコールバックを有効にするには、Accountマネージャーまたはサポートチームにお問い合わせください。

これにより、以下の方法を使用してチャンネルの現在の状態が表示されます。 status フィールドにいる：

• blocked - リクエストがブロックされました。これは、例えば、ベロシティルールによる場合や、指定された番号がVOIPである場合などに発生することがあります。
• failed - リクエストが失敗しました。これは、たとえば、指定された番号が有効な番号ではなかった場合などに発生することがあります。
• expired - リクエストは所定の時間内に完了しなかった。
• action_pending - ユーザーが認証手順を開始するための操作を一切行っていない。これは、「サイレント認証」および「サイレント認証（アドバンスト）」にのみ適用されます。例えば、 check_url ユーザーがサイレント認証を開始するために割り当てられた関数が、まだ呼び出されていません。

{
   "request_id": "c11236f4-00bf-4b89-84ba-88b25df97315",
   "triggered_at": "2020-01-01T14:00:00.000Z",
   "type": "event",
   "channel": "sms",
   "channel_order": 2,
   "status": "expired",
   "channel_initiated_at": "2020-01-01T14:00:05.000Z",
   "channel_finalized_at": "2020-01-01T14:00:10.000Z",
   "client_ref": "my-personal-ref"
}

サイレント認証およびサイレント認証（上級）

「サイレント認証」および「サイレント認証（詳細）」の場合、初期の イベントのコールバック には、以下のものが含まれます action_pending ステータスと、ある action …を含むオブジェクト check_url チェックを完了するには、ユーザーの端末から呼び出しを行う必要があります：

{
   "request_id": "c11236f4-00bf-4b89-84ba-88b25df97315",
   "triggered_at": "2020-01-01T14:00:00.000Z",
   "type": "event",
   "channel": "silent_auth",
   "status": "action_pending",
   "mode": "advanced",
   "action": {
      "type": "check",
      "check_url": "https://api.nexmo.com/v2/verify/:request_id/silent-auth/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": "silent_auth",
         "initiated_at": "2020-01-01T14:00:00.000Z",
         "status": "cancelled",
         "mode": "advanced"
      },
      {
         "channel": "sms",
         "initiated_at": "2020-01-01T14:05:00.000Z",
         "status": "expired"
      },
      {
         "channel": "whatsapp",
         "initiated_at": "2020-01-01T14:10:00.000Z",
         "status": "completed"
      },
      {
         "channel": "voice",
         "initiated_at": "2020-01-01T14:15:00.000Z",
         "status": "unused"
      }
   ],
   "client_ref": "my-personal-ref"
}

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