Skip to contentSkip to navigationSkip to topbar
Rate this Page:

Authy Webhooks API


(warning)

Warning

As of November 2022, Twilio no longer provides support for Authy SMS/Voice-only customers. Customers who were also using Authy TOTP or Push prior to March 1, 2023 are still supported. The Authy API is now closed to new customers and will be fully deprecated in the future.

For new development, we encourage you to use the Verify v2 API.

Existing customers will not be impacted at this time until Authy API has reached End of Life. For more information about migration, see Migrating from Authy to Verify for SMS(link takes you to an external page).

Set a webhook to be called after a publically visible event happens and improve insight into your Authy application's usage. The API has three endpoints:

(information)

Info

Twilio can send your web application an HTTP request when certain events happen, such as an incoming text message to one of your Twilio phone numbers. These requests are called webhooks, or status callbacks. For more, check out our guide to Getting Started with Twilio Webhooks. Find other webhook pages, such as a security guide and an FAQ in the Webhooks section of the docs.


Signing Requests

signing-requests page anchor

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 params:


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

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


_10
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.


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

4. Generate a unique nonce(link takes you to an external page)

Your language of choice likely has a nonce generator library, such nonce(link takes you to an external page) in Node.js.


_10
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.


_10
data = nonce + "|" + http_method + "|" + url + "|" + params_in_url_format
_10
"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(link takes you to an external page).


_10
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(link takes you to an external page).


_10
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.


_10
request.headers["X-Authy-Signature"] = digest_in_base64
_10
request.headers["X-Authy-Signature-Nonce"] = nonce
_10
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.(link takes you to an external page)

authy settings webhooks api keys.


_10
POST https://api.authy.com/dashboard/json/application/webhooks

Parameters

create-webhook-parameters page anchor
NameTypeDescription
urlstringThe callback url to receive registered events in the webhook (🏢 not PII )
eventsarray stringThe list of events to monitor by the webhook. See available events (🏢 not PII )
namestringIdentifying name for your webhook. (🏢 not PII )
app_api_keystringFound in the application settings tab in the Twilio Console.(link takes you to an external page) See webhooks API keys. (🏢 not PII )
access_keystringFound in the application settings tab in the Twilio Console.(link takes you to an external page) See webhooks API keys. (🏢 not PII )
NameTypeDescription
webhookobjectDetails about the created webhook. See below for more details. (🏢 PII )
messagestringAuthy API response description. (🏢 PII )
successbooleanReturns true if the request was successful. (🏢 not PII )

The response will be JSON with the following structure:


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

Create an Authy Webhook

create-an-authy-webhook page anchor
curl

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

Output

_14
{
_14
"webhook": {
_14
"id": "WH_0c04...",
_14
"name": "my webhook",
_14
"account_sid": "ACec7...",
_14
"service_id": "56...",
_14
"url": "https://example.com/callback-action",
_14
"signing_key": "WSK_ovh...",
_14
"events": ["phone_verification_started"],
_14
"creation_date": "2017-03-30T20:10:37.121+00:00"
_14
},
_14
"message": "Webhook created",
_14
"success": true
_14
}

Webhooks can be configured for the following events:

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



_10
DELETE https://api.authy.com/dashboard/json/application/webhooks/:webhook_id

NameTypeDescription
webhook_idStringThe webhook id (🏢 not PII )
NameTypeDescription
messagestringAuthy API response description. (🏢 PII )
successbooleanReturns true if the request was successful. (🏢 not PII )
curl

_10
curl -X DELETE "https://api.authy.com/dashboard/json/application/webhooks/WH_0c04..." \
_10
-d app_api_key=""tLPrf... \
_10
-d access_key="usQ4z..." \
_10
-H "X-Authy-Signature-Nonce: 1427849783.886085" \
_10
-H "X-Authy-Signature: QB+u2hFTj+fstAEbSUQUfA7409uKJTL2W17MrRuk3OE="

Output

_10
{
_10
"message": "Webhook deleted",
_10
"success": true
_10
}



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

This endpoint does not require parameters.

NameTypeDescription
webhooksarrayArray of webhook objects. See examples for detailed response structure. (🏢 PII )
successbooleanReturns true if the request was successful. (🏢 not PII )
curl

_10
curl -X GET https://api.authy.com/dashboard/json/application/webhooks \
_10
-d app_api_key="tLPrf..." \
_10
-d access_key="usQ4z..." \
_10
-H "X-Authy-Signature-Nonce:1427849783.886085" \
_10
-H "X-Authy-Signature: QB+u2hFTj+fstAEbSUQUfA7409uKJTL2W17MrRuk3OE="

Output

_29
{
_29
"webhooks":[
_29
{
_29
"id":"WH_0c04...",
_29
"name":"my webhook",
_29
"account_sid":"ACec7...",
_29
"service_id":"56...",
_29
"url":"https://example.com/callback-action",
_29
"signing_key":"WSK_ovh...",
_29
"events":[
_29
"phone_verification_started"
_29
],
_29
"creation_date":"2018-03-30T20:10:37.121+00:00"
_29
},
_29
{
_29
"id":"WH_0c05...",
_29
"name":"my other webhook",
_29
"account_sid":"ACec7...",
_29
"service_id":"57...",
_29
"url":"https://example.com/callback-action",
_29
"signing_key":"WSK_ivf...",
_29
"events":[
_29
"phone_verification_started"
_29
],
_29
"creation_date":"2018-03-30T20:10:37.121+00:00"
_29
}
_29
],
_29
"success":true
_29
}


You can find more examples of how to use Authy Webhooks in the Node implementation of the webhooks-api(link takes you to an external page) 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.


Rate this Page: