Menu

Expand
Rate this page:

Authy Webhooks API

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.

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:

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

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

params = {b: "val|ue&2", a: "value1"}
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.

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

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

Webhooks API Keys

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.

authy settings webhooks api keys

Create a webhook

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

Parameters

Name Type Description
url string The callback url to receive registered events in the webhook (🏢 not PII )
events array string The list of events to monitor by the webhook. See available events (🏢 not PII )
name string Identifying name for your webhook. (🏢 not PII )
app_api_key string Found in the application settings tab in the Twilio Console. See webhooks API keys. (🏢 not PII )
access_key string Found in the application settings tab in the Twilio Console. See webhooks API keys. (🏢 not PII )

Response

Name Type Description
webhook object Details about the created webhook. See below for more details. (🏢 PII )
message string Authy API response description. (🏢 PII )
success boolean Returns true if the request was successful. (🏢 not PII )

The response will be JSON with the following structure:

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
Loading Code Sample...
        
        

        Create an Authy Webhook

        Available Events

        Webhooks can be configured for the following events:

        Delete a webhook

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

        URL

        Name Type Description
        webhook_id String The webhook id (🏢 not PII )

        Parameters

        Name Type Description
        app_api_key string Found in the application settings tab in the Twilio Console. See webhooks API keys. (🏢 not PII )
        access_key string Found in the application settings tab in the Twilio Console. See webhooks API keys. (🏢 not PII )

        Response

        Name Type Description
        message string Authy API response description. (🏢 PII )
        success boolean Returns true if the request was successful. (🏢 not PII )
        Loading Code Sample...
              
              

              Delete an Authy Webhook

              List Webhooks

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

              This endpoint does not require parameters.

              Response

              Name Type Description
              webhooks array Array of webhook objects. See examples for detailed response structure. (🏢 PII )
              success boolean Returns true if the request was successful. (🏢 not PII )
              Loading Code Sample...
                    
                    

                    List Authy Webhook

                    More Examples

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

                    Verify Callbacks

                    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:

                    Need some help?

                    We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

                    Loading Code Sample...
                          
                          
                          

                          Thank you for your feedback!

                          Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

                          Sending your feedback...
                          🎉 Thank you for your feedback!
                          Something went wrong. Please try again.

                          Thanks for your feedback!

                          thanks-feedback-gif