ウェブフック

Webhookを使用すると、開発者はHTTP経由でユーザーのイベント通知を受け取るURLを登録できます。登録されたWebhookは、グローバルに一意なIDによって一意に識別されます。その後のすべての操作は、リソースパスにこのIDを取ります。

外部エンドポイント

Webhook は POST をサポートし、必要なタイムアウト内に Http Status 200 で応答する必要があります。Webhook 通知は最大 5 回再試行され、再試行の間は 10 秒間休止します。失敗した Webhook には、それ以降のイベントは配信されません。Webhookを更新すると、"失敗 "ステータスが解除され、再びイベント通知の受信が開始されます。

Webhook エンドポイントはタイムリーに応答する必要があります。Webhookの配信が成功と判定されるためには、システムが3秒以内にWebhook URLサーバーへの接続を確立し、2秒以内にHttp Status 200を受信する必要があります。

有効期限

Webhook登録は、ある期間が経過すると失効します (expireAt通常は 10 日間）が経過すると、通知を受け取れなくなります。ただし、期限切れ（または期限切れでない）の Webhook は無期限に更新できます。期限切れのウェブフックは、ある時点で永久に削除されます (purgeAt).ウェブフックが更新されると renewedAt そして renewedBy プロパティには現在時刻が設定され expireAt そして purgeAt プロパティは renewedAt.

ウェブフックが更新されると、失敗フラグがリセットされますが、それ以外の過去の配信統計は削除されません。

メタデータ、署名、重複排除

すべての Webhook 通知イベントとともに、Webhook イベントとその配信に関するメタデータは、HTTP ヘッダーに含まれるか、リクエスト・ボディ自体に含まれるか、まったく含まれないかのいずれかです。リクエスト・ボディの metadataPolicy プロパティは、希望するメタデータの配信を制御します。

Webhookメタデータは以下のプロパティで構成される：

このメタデータが配信されるためには metadataPolicy のいずれかに設定しなければならない。 HEADER または BODY.さらに、署名は以下の場合にのみ設定されます。 signingAlgo に設定されている。 HMAC_SHA256 と空でない signingKey が設定されている。

システムはタイムアウトしたウェブフック・エントリーの配信を再試行するので、エンドポイント自身は URL への複数の POST が同じイベントか異なるイベントかを知る必要があります。そのため deliveryId と attempt プロパティは、個別の通知イベントと再試行を区別するために必要な情報をエンドポイントに提供する。

イベント

Webhook通知イベントは、例えば以下のようなフォーマットを持っています：

{
    "event": {
        "accountId": "-1",
        "direction": "OUTBOUND",
        "duration": 0,
        "externalId": "abc1234-288c-40d3-8ec8-3618a3ae7698_123",
        "id": "abc1234a806d07a6ff17ba",
        "internal": false,
        "phoneNumber": "xxxxxxxxxx",
        "startTime": "2020-10-01T16:10:06.000+0000",
        "state": "RINGING",
        "type": "CALL",
        "ucpType": "VBS",
        "userId": "1234"
    },
    "metadata": {
        "attempt": 1,
        "deliveryId": "abc1234-2795-446c-be6b-7cba85c6bba2",
        "signature": "abc1234663a4d0589ec092677b4af18b4a747ac8cfa6198a57b8c6bfec9bf28a",
        "webhookId": "abc1234-c1ad-4a14-a30b-69dd92f57af2"
    }
}

について metadata プロパティが含まれるのは metadataPolicy に設定されている。 BODY.その signatureのjson値から計算される。 event プロパティでは、すべてのプロパティはアルファベット順に並べられ、プロパティ名とその値の間には空白はありません。例えば、上の例のシグネチャは event ボディは以下のjsonで計算される：

{"accountId": "-1","direction": "OUTBOUND","duration": 0,"externalId": "abc1234-288c-40d3-8ec8-3618a3ae7698_123","id": "abc1234a806d07a6ff17ba","internal": false,"phoneNumber": "xxxxxxxxxx","startTime": "2020-10-01T16:10:06.000+0000","state": "RINGING","type": "CALL","ucpType": "VBS","userId": "1234"}

そして秘密鍵を使って mysecretkey には次のような署名がある：

95aafd08cb72b1f9216ccd002b8917b04e41ecb19276ae759241fdc0cbb53fb5.

リダイレクション・ポリシー

Webhook エンドポイントは、Http ステータス 302 または 307 を返すことが許可されています。システムはリダイレクトに従いますが、ある程度の上限があり、それを超えると Webhook は失敗したものとしてマークされます。Webhook エンドポイントが 302 を返した場合、Webhook イベントはレスポンスで見つかった URL への Http Get として配信されます。 Location ヘッダを返します。307 が返された場合、Webhook イベントはレスポンスで見つかった URL への Http POST として配信されます。 Location ヘッダーを使用する。

統計

システムは試行回数、成功回数、失敗回数の合計を記録する。また、最後の成功と失敗の日時も記録されます。失敗の場合、最新の Http ステータスコードと説明メッセージも記録されます。ウェブフックが更新されると isFailed にリセットされる。 falseその他の統計はすべて、情報提供のために保管されている。

Webhook は、特定の配信に対するすべての再試行が完了するまで、成功とも失敗とも見なされません。例えば、システムがウェブフック配信を5回再試行し失敗した場合、それは1回の追加試行と失敗としてカウントされます。

Webhook 統計は、URLが一時的に利用できない場合（例えば、システムメンテナンスのため）に見逃される可能性のあるイベントを発見するために使用することができます。このような場合、見逃されたイベントは lastSuccess.メンテナンス後にシステムが復旧したら、すぐに既存のウェブフックを更新するのがよい方法です。