Menu

Expand
Rate this page:

Authy Webhooks API

For new development, we encourage you to use the Verify API instead of the Authy API. The Verify API is an evolution of the Authy API with continued support for SMS, voice, and email one-time passcodes, an improved developer experience and new features including:

  • Twilio helper libraries in JavaScript, Java, C#, Python, Ruby, and PHP
  • Access via the Twilio CLI
  • Improved Visibility and Insights
  • Push authentication SDK embeddable in your own application

You are currently viewing the Authy API. The Authy API will continue to be maintained, but any new features and development will be on the Verify API. Check out the FAQ for more information and Verify API Reference to get started.

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
        
        
        
        

        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 )
              
              
              
              

              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 )
                    
                    
                    
                    

                    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 browsing the Twilio tag on Stack Overflow.

                          
                          
                          

                          Thank you for your feedback!

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

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

                          Thanks for your feedback!

                          Refer us and get $10 in 3 simple steps!

                          Step 1

                          Get link

                          Get a free personal referral link here

                          Step 2

                          Give $10

                          Your user signs up and upgrade using link

                          Step 3

                          Get $10

                          1,250 free SMSes
                          OR 1,000 free voice mins
                          OR 12,000 chats
                          OR more