Authy Webhooks API

All Webhook API requests require the X-Authy-Signature header. These are the steps required to generate the header and sign a request:

1. Create a string variable using the URL without parameters:

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

2. Create a string variable with the HTTP method in upper case (GET, POST, DELETE):

http_method = "POST"

3. Sort the list of parameters in case-sensitive order and convert them to URL format

Both key and value should be URL-encoded.

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

4. Generate a unique nonce

Your language of choice likely has a nonce generator library, such nonce in Node.js.

nonce = "1427849783.886085"

5. Join nonce, http_method, url and params_in_url_format together with the | character:

Note: the string should contain exactly 3 | characters.

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

6. Hash the resulting data using HMAC-SHA256, using your api_signing_key as the key:

Get your API signing key from "Webhooks API Keys" section of the application settings tab in the Twilio Console.

digest = hmac_sha256(data, api_signing_key)

7. Base64 encode the digest:

Base64 encoding should not contain line feeds. It must be encoded as described in the RFC 4648.

digest_in_base64 = encode_in_base64(digest)

8. Make the HTTP request with specified headers

Send the digest_in_base64 in the X-Authy-Signature header

Send the nonce in the X-Authy-Signature-Nonce header.

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

Webhook API requests require the app_api_key and access_key parameters. Signing the request (step 6 above) requires the api_signing_key. These are found in the application settings tab in the Twilio Console.

Expand image

The response will be JSON with the following structure:

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

1
curl -X POST "https://api.authy.com/dashboard/json/application/webhooks" \
2
   -d name="my webhook" \
3
   -d app_api_key=""tLPrf... \
4
   -d access_key="usQ4z..." \
5
   -d url="https://example.com/callback-action" \
6
   -d events[]="phone_verification_started" \
7
   -H "X-Authy-Signature-Nonce: 1427849783.886085" \
8
   -H "X-Authy-Signature: 5RgJYUuz9m/rhi6XPjAjKUtNOJqPgMnP9GKBqWJEGFg="

1
{
2
  "webhook": {
3
    "id": "WH_0c04...",
4
    "name": "my webhook",
5
    "account_sid": "ACec7...",
6
    "service_id": "56...",
7
    "url": "https://example.com/callback-action",
8
    "signing_key": "WSK_ovh...",
9
    "events": ["phone_verification_started"],
10
    "creation_date": "2017-03-30T20:10:37.121+00:00"
11
  },
12
  "message": "Webhook created",
13
  "success": true
14
}

Webhooks can be configured for the following events:

• account_recovery_approved
• account_recovery_canceled
• account_recovery_started
• custom_message_not_allowed
• device_registration_completed
• multidevice_setting_changed
• one_touch_request_responded (note: one_touch refers to the Authy Push Authentication API
• phone_change_canceled
• phone_change_pin_sent
• phone_change_requested
• suspended_account
• token_invalid
• token_verified
• too_many_code_verifications
• totp_token_sent_via_call
• totp_token_sent
• unlock_method_changed
• user_account_deleted
• user_added
• user_phone_changed

The following events are specific to our legacy phone verification API. Please consider upgrading to Verify V2:

• phone_verification_code_is_invalid
• phone_verification_code_is_valid
• phone_verification_failed
• phone_verification_not_found
• phone_verification_started
• too_many_phone_verifications

GET https://api.authy.com/dashboard/json/application/webhooks

This endpoint does not require parameters.

You can find more examples of how to use Authy Webhooks in the Node implementation of the webhooks API on Github.

The Twilio Authy webhooks service will send a callback every time a registered event occurs. The response will be coded in JWT and signed with the signing_key for the registered webhook. Use that signing_key to validate the response when you decode it.

Visit this page for more information on validating webhooks.