Authy Webhooks API

Authy offers webhooks capabilities through a REST API. The API is designed to use HTTP response codes to indicate status, and include more information in the body of the response in JSON.

API Endpoints

Currently the following endpoints exist: Create a webhook, Delete a webhook and List webhooks

  • These are /dashboard/json/application/webhooks api calls requiring passage of X-Authy-Signature-Nonce and X-Authy-Signature as header parameters

  • These are /dashboard/json/application/webhooks api calls requiring passage of app_api_key and access_key as parameters

Available Events

Webhooks can be configured for the following events:

Signing Requests

Most of the end points listed in this document require a signature. These are the steps to successfully 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 (number once):

  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:

  digest = hmac_sha256(data, api_signing_key)

7. Encode in base64 the digest. Base64 encoding should not contain line feeds. It must be encoded as described in the RFC 4648 (https://tools.ietf.org/html/rfc4648):

digest_in_base64 = encode_in_base64(digest)

8. Send the digest_in_base64 in an http header called X-Authy-Signature and 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)

Verify Callbacks

The webhooks service will send back 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. You should use that signing_key to verify the response when you decode it.

Create a webhook

POST /dashboard/json/application/webhooks

Parameters

Name Type Description
url String The callback url to receive registered events in the webhook
events Array String The list of events to monitor by the webhook

Response

The response will be JSON 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

Examples

Creating a 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
}

Delete a webhook

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

Parameters

Name Type Description
webhook_id String The webhook id

Response

The response will be JSON following structure:

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

Examples

Deleting a 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
}

List Webhooks

This endpoint does not require parameters

Response

The response will be JSON following structure:

webhooks: List of webhooks
success: Whether yes or no request was success

Examples

Deleting a 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="

{
  "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": "2017-03-30T20:10:37.121+00:00"
    },
   {
        "id": "WH_0c05...",
        "name": "my webhook",
        "account_sid": "ACec7...",
        "service_id": "57...",
        "url": "https://example.com/callback-action",
        "signing_key": "WSK_ivf...",
        "events": ["phone_verification_started"],
        "creation_date": "2017-03-30T20:10:37.121+00:00"
    }
  ],
  "success": true
}

Code Samples

You can find more examples of how to use Authy Webhooks in the authy-testing-sample on Github.

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.