メニュー

Expand
Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Authy Webhooks API

AuthyはREST APIを通じてWebhook機能を提供します。 APIはHTTPレスポンスコードをステータスを示すために使用し、レスポンスの本文(body)にJSON形式で詳細を含むよう設計されています。

APIエンドポイント

現在、下記のエンドポイントが使用可能です。: Webhookを作成するWebhookを削除するWebhookを一覧する

  • これらはヘッダーパラメーターとしてX-Authy-Signature-NonceおよびX-Authy-Signatureの受け渡しが必要となる /dashboard/json/application/webhooks API呼び出しです。

  • これらはパラメーターとしてapp_api_keyおよびaccess_keyの受け渡しが必須な /dashboard/json/application/webhooks API呼び出しです。

利用可能なイベント

Webhookは下記のイベントに対して構成できます:

署名リクエスト

このドキュメントに一覧されているほとんどのエンドポイントには署名が必要です。 下記は、正しくリクエストに署名するための手順になります:

1. パラメーターを除いたURLを使用した文字列変数を作成します:

  url = "https://api.authy.com/dashboard/json/application/webhooks"

2. 大文字 (GET、POST、DELETE) でHTTPメソッドの文字列変数を作成します:

  http_method = "POST"

3. 受信したパラメーターの一覧を大文字と小文字を区別させて並べ替え、URLの形式に変換します(キーと値、双方ともURLエンコーディングされている必要があります):

  params = {b: "val|ue&2", a: "value1"}
  sorted_params = "a=value1&b=val%7Cue%262"

4. 一意なナンス(一度のみ使用される番号)を生成します:

  nonce = "1427849783.886085"

5. nonce、http_method、url、およびparams_in_url_formatを | の文字で連結します。

NOTE: The string should contain exactly 3 | characters.

  data = nonce + "|" + http_method + "|" + url + "|" + params_in_url_format 
  #=> "1427849783.886085|POST|https://api.authy.com/dashboard/json/application/webhooks|a=value1&b=val%7Cue%262"

6. HMAC-SHA256を使用し、ご自身のapi_signing_keyを使用して結果データをハッシュ化します。

  digest = hmac_sha256(data, api_signing_key)

7. ダイジェストをBase64でエンコードします。 Base64エンコーディングには行送りが含まれないようにしてください。RFC4648(https://tools.ietf.org/html/rfc4648) に記載されたとおりにエンコードされなければなりません:

digest_in_base64 = encode_in_base64(digest)

6. X-Authy-Signatureという名前のHTTPヘッダーにdigest_in_base64を、X-Authy-Signature-Nonceヘッダーにnonceをそれぞれ送信します。

  request.headers["X-Authy-Signature"] = digest_in_base64
  request.headers["X-Authy-Signature-Nonce"] = nonce
  make_request(request)

コールバックを検証する

Webhookサービスは登録済みイベントが発生すると毎回コールバックを返送し、登録済みWebhookに対するレスポンスはJWTにエンコードされ、signing_keyで署名されます。 デコードの際は、このsigning_keyを使用してレスポンスを検証するようにしてください。

Webhookを作成する

POST /dashboard/json/application/webhooks

パラメーター

名前 Type 概要
url 文字列 The callback url to receive registered events in the webhook (🏢 not PII )
Events 配列文字列 The list of events to monitor by the webhook (🏢 not PII )

レスポンス

レスポンスは下記の構造を持つJSONになります:

webhook: webhook object
   id: Webhook id
   name: Webhook name
   account_sid: Twilio owner account id
   service_id: Authy application serial id
   url: Callback url
   signing_key: The key to verify JWT response received by the callback url
   events: List of events which will trigger webhook callbacks
   objects: Objects involved in the event. This is specific by event type.
   creation_date: Date in which webhook was created
message: Authy api response message
success: Whether yes or no request was success

サンプル

Webhookの作成

$ curl -X POST "https://api.authy.com/dashboard/json/application/webhooks" \
   -d name="my webhook" \
   -d app_api_key=""tLPrf... \
   -d access_key="usQ4z..." \
   -d url="https://example.com/callback-action" \
   -d events[]="phone_verification_started" \
   -H "X-Authy-Signature-Nonce: 1427849783.886085" \
   -H "X-Authy-Signature: 5RgJYUuz9m/rhi6XPjAjKUtNOJqPgMnP9GKBqWJEGFg="
{
  "webhook": {
      "id": "WH_0c04...",
      "name": "my webhook",
      "account_sid": "ACec7...",
      "service_id": "56...",
      "url": "https://example.com/callback-action",
      "signing_key": "WSK_ovh...",
      "events": ["phone_verification_started"],
      "creation_date": "2017-03-30T20:10:37.121+00:00"
  },
  "message": "Webhook created",
  "success": true
}

Webhookを削除する

DELETE /dashboard/json/application/webhooks/:webhook_id

パラメーター

名前 Type 概要
webhook_id 文字列 The webhook id (🏢 not PII )

レスポンス

レスポンスは下記の構造を持つJSONになります:

message: Authy api response message
success: Whether yes or no request was success

サンプル

Webhookの削除

$ curl -X DELETE "https://api.authy.com/dashboard/json/application/webhooks/WH_0c04..." \
   -d app_api_key=""tLPrf... \
   -d access_key="usQ4z..." \
   -H "X-Authy-Signature-Nonce: 1427849783.886085" \
   -H "X-Authy-Signature: QB+u2hFTj+fstAEbSUQUfA7409uKJTL2W17MrRuk3OE="
{
  "message": "Webhook deleted",
  "success": true
}

Webhookを一覧する

このエンドポイントはパラメーターを必要としません。

レスポンス

レスポンスは下記の構造を持つJSONになります:

webhooks: List of webhooks
success: Boolean: whether request was success

サンプル

List webhooks

$ curl -X GET https://api.authy.com/dashboard/json/application/webhooks \
-d app_api_key="tLPrf..." \
-d access_key="usQ4z..." \
-H "X-Authy-Signature-Nonce:1427849783.886085" \
-H "X-Authy-Signature: QB+u2hFTj+fstAEbSUQUfA7409uKJTL2W17MrRuk3OE="
{
  "webhooks":  [
     {
        "id": "WH_0c04...",
        "name": "my webhook",
        "account_sid": "ACec7...",
        "service_id": "56...",
        "url": "https://example.com/callback-action",
        "signing_key": "WSK_ovh...",
        "events": ["phone_verification_started"],
        "creation_date": "2018-03-30T20:10:37.121+00:00"
    },
   {
        "id": "WH_0c05...",
        "name": "my other webhook",
        "account_sid": "ACec7...",
        "service_id": "57...",
        "url": "https://example.com/callback-action",
        "signing_key": "WSK_ivf...",
        "events": ["phone_verification_started"],
        "creation_date": "2018-03-30T20:10:37.121+00:00"
    }
  ],
  "success": true
}

コード例

GitHub上のwebhooks-apiのNode実装でAuthy Webhookの使用方法のつい華麗についてご覧いただけます。

Rate this page:

ヘルプが必要ですか?

誰しもが一度は考える「コーディングって難しい」。そんな時は、お問い合わせフォームから質問してください。 または、Stack Overflow でTwilioタグのついた情報から欲しいものを探してみましょう。