ウェブフック

WebhookはAPIの拡張機能ですが、お客様のコードがAPIプラットフォームからデータをリクエストする代わりに、Vonageがお客様にデータを送信します。データはお客様のアプリケーションへのウェブリクエストとして届きます。Webhookは、Number Insight APIへの非同期リクエストなど、以前のAPI呼び出しの結果である場合もあります（このタイプのWebhookは「コールバック」とも呼ばれます）。Webhookは、着信やメッセージなどのイベントをアプリケーションに通知するためにも使用されます。

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

Webhooksワークフロー

Webhookでは、Webhookを送信するURLが設定されていることが重要です。データが利用可能になると、VonageはHTTPリクエストとしてアプリケーションにWebhookを送信します。アプリケーションは、データを正常に受信したことを示すHTTP成功コードで応答する必要があります。

そのプロセスは次のようなものだ：

Webhooksは、着信やメッセージ、通話ステータスの変更などのイベントに対して、Vonageがお客様のアプリケーションに情報を送信する便利なメカニズムを提供します。Webhooksはまた、リクエストの後に利用可能になる配達受領書などのフォローアップ情報を送信するために使用することもできます。

どのAPIがウェブフックをサポートしていますか？

サポートされているVonage APIへのリクエストから得られる情報は、HTTPサーバ上のWebhookエンドポイントへのHTTPリクエストとして送信されます。ウェブフックエンドポイントを設定するには Vonageダッシュボード.

VonageはWebhookを使用して以下の情報を送信および取得します：

ウェブフック・エンドポイントの設定

Webhookは、受信メッセージと配信レシートを配信するために使用されます。

着信メッセージ

受信メッセージに使用するウェブフックを設定するには あなたのナンバーズ セクションをクリックします。バーチャル番号の「edit」をクリックし、以下のように設定します。 コールバックURL.

を使用することもできます。 Vonage CLI をクリックして、個々の番号の着信メッセージのエンドポイントを設定します。

領収書

参照 領収書 のガイドを参照してください。

ウェブフックの受信

Vonage webhooksと対話する：

1. Vonageアカウントを作成する。
2. Vonageから送信または要求された情報を処理するスクリプトを記述します。あなたのサーバーは、Vonage からのインバウンドメッセージに対して成功ステータスコード (200 OK から 205 Reset Content までのステータスコード) で応答しなければなりません。を返さなければなりません。 2xx コードは、Vonageサーバーにコールバック配信を再試行させます。
3. スクリプトをサーバーにデプロイして公開する（ローカルで開発する場合は ングロク).
4. ウェブフック・エンドポイントを設定する を使用したいAPIに追加する。
5. そのWebhookをトリガーするアクション（SMSの送信など）を取る。

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

署名付きウェブフックのデコード

Webhookの署名は デフォルト これらは、Messages API、Dispatch API、Verify API、Voice APIのためのものです。これらは、リクエストがVonageから来ており、そのペイロードが転送中に改ざんされていないことをアプリケーションが確認するための方法を提供します。リクエストを受信する際、受信するWebhookは、あなたの署名シークレットで署名されたJWTトークンを認可ヘッダに含めます。

注:以前に作成された Voice アプリケーションでは、Signed Webhooks はデフォルトでオフになっています。手動でオンにするには、ダッシュボードのアプリケーション設定に移動し、音声機能セクションの「高度な機能を表示」リンクをクリックし、「署名付きWebhook」をオンにします。 署名付きWebhookを使用する チェックする：

また、このチェックで新規アプリケーションをオフにすることもできます（推奨しません。）

署名されたWebhookを検証することで、以下のようなセキュリティ上の利点がある：

• リクエストがVonageから発信されたものであることを確認する機能
• 転送中にメッセージが改ざんされていないことの確認
• インターセプトとリプレーに対するディフェンス

署名付きWebhookの検証

署名されたウェブフックの検証には2つの部分がある：

1. リクエストの検証
2. ペイロードの検証（オプション）

リクエストの検証

Webhookは、JWTを Authorization ヘッダを使用する。リクエストに署名するためにどの署名秘密が使われたかを特定するために、 JWTクレームに含まれるAPIキーを使用する。リクエストに署名するために使われた秘密は、JWTヘッダーに関連付けられた署名秘密に対応する。 api_key JWTクレームに含まれる。署名の秘密は ダッシュボード.署名の安全性を確保するために、署名の秘密は32ビット以上にすることが推奨される。

ペイロードが輸送中に改ざんされていないことを検証する。

リクエストの真正性をVerifyしたら、オプションで、ペイロードのSHA-256 ハッシュを payload_hash フィールドが見つかる。これらが一致しない場合、ペイロードは転送中に改ざんされたことになる。ペイロードをVerifyする必要があるのは、HTTPSではなくHTTPを使用している場合だけです。 MITM攻撃.

以下のコード例では、Webhook の署名を Verify する方法を示しています。HTTPS プロトコルを使用することを推奨します。クライアント側とサーバー側の両方でリクエストとレスポンスが暗号化されるからです。

npm install @vonage/jwt express

const app = require('express')();
const bodyParser = require('body-parser');

app.use(bodyParser.json());
app.use(bodyParser.urlencoded({
  extended: true,
}));

app
  .route('/webhooks/inbound-message')
  .post(handleInboundMessage);

const handleInboundMessage = (request, response) => {
  const token = request.headers.authorization.split(' ')[1];
  if (verifySignature(token, VONAGE_API_SIGNATURE_SECRET)) {
    console.log('Valid signature');
  } else {
    console.log('Invalid signature');
  }

  response.send(200);
};

app.listen(process.env.PORT || 3000);

composer require vonage/client

pip install vonage python-dotenv fastapi[standard]

import os
from os.path import dirname, join

from dotenv import load_dotenv

# Load the environment
envpath = join(dirname(__file__), '../.env')
load_dotenv(envpath)


VONAGE_SIGNATURE_SECRET = os.getenv('VONAGE_SIGNATURE_SECRET')

from fastapi import FastAPI, Request
from vonage_jwt.verify_jwt import verify_signature

app = FastAPI()


@app.get('/inbound')
async def verify_signed_webhook(request: Request):
    # Need to get the JWT after "Bearer " in the authorization header
    auth_header = request.headers["authorization"].split()
    token = auth_header[1].strip()

    if verify_signature(token, VONAGE_SIGNATURE_SECRET):
        print('Valid signature')
    else:
        print('Invalid signature')

署名済みJWTのサンプル

// header
{
  "alg": "HS256",
  "typ": "JWT",
}
// payload
{
  "iat": 1587494962,
  "jti": "c5ba8f24-1a14-4c10-bfdf-3fbe8ce511b5",
  "iss": "Vonage",
  "payload_hash" : "d6c0e74b5857df20e3b7e51b30c0c2a40ec73a77879b6f074ddc7a2317dd031b",
  "api_key": "a1b2c3d",
  "application_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
}

署名付きJWTヘッダー

署名付きJWTヘッダーの内容は以下の表に記述されている：

署名付きJWTペイロード

署名付きJWTペイロードの内容は、先に示した署名付きJWTのサンプルに含まれる値を用いて、以下の表に記述されている：

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

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

ファイアウォールの設定

インバウンドトラフィック（配信レシートを含む）を制限する場合は、ファイアウォールの承認IPアドレスリストにVonage IPアドレスを追加する必要があります。この方法の詳細については、ナレッジベースをご覧ください：

• 音声IPレンジ
• SMS IPレンジ
• メッセージと派遣IP範囲
• Numbersインサイトアドバンスド非同期IPレンジ

ウェブフックのデバッグのヒント

小さく始める - Webhookを受信したときに応答し、おそらくいくつかのデバッグ情報を表示するために、思いつく限り最小のスクリプトを公開する。これにより、URLがあなたが考えているものであることを確認し、アプリケーションの出力やログを見ることができます。

守備的なコード - 先に進んで使用する前に、データ値が存在し、期待したものを含んでいることを検査してください。あなたのセットアップによっては、予期せぬデータを受け取る可能性があるので、常に心に留めておいてください。

例を見てみよう - Vonageは、できるだけ多くの開発者をサポートするために、いくつかの技術スタックで実装された例を提供しています。Webhooksを使用したコード例については、以下を参照してください：

• SMSを受信する
• 納品書の取り扱い
• 着信を受ける

また、使用しているAPIのドキュメントのコード・スニペット・セクションをチェックすることもできる。

参照

• ウェブフックの種類とアプリケーションの機能についての詳細は 申請書類.