Verify Events Onboarding Guide

Twilio Console allows you to onboard completely within the Console itself, no code or command line required.

First, you'll need to enable Verify Events in your Twilio Console by navigating to the Twilio Console > Verify > Services page and selecting your Service. This will open the Service settings page where you can select the General tab and turn on the Verify Events Subscribed service option for that Service.

Next, if you haven't used Event Streams before, you'll want to pin it to your Twilio Console so it's easily accessible. Navigate to the Twilio Console > Explore Products page. In the Developer tools product section, select the pin icon next to Event Streams to keep it pinned to your sidebar.

Now let's create a new sink! A sink is the destination where events will be delivered.

Navigate to the Twilio Console > Event Streams > Manage page and select Create new sink.

Give your sink a description. This should be a recognizable, human-readable name to help you identify the sink easily such as verify-events-webhook-sink.

Next, select your sink type. In this guide we'll be setting up the webhook sink type.

Before finalizing the sink's creation, you'll need to provide some additional details and configuration information. We recommend setting Batch to False so you can handle and process each event individually.

Once your sink is created, you'll be prompted to validate your sink connection.

You can optionally validate the webhook sink connection before proceeding. Validating the connection will trigger a send of a test event to your webhook endpoint URL. Once your webhook endpoint receives the test, submit the test event ID from the event's request body to complete the validation.

To finish up, we need to create a subscription for your sink. A subscription defines which events will be sent to your sink.

Navigate to the Twilio Console > Event Streams > Manage page, select Create and choose New subscription.

When you reach the Select event types for this subscription section, select Verify under the Product groups menu.

You can subscribe to one or more event types. Select all the events that you would like streamed to your sink destination by choosing their schema version (schema version 1 is the oldest). Read more about each Verify event type here.

Expand image

That's it! Once the subscription is created, Verify events will start flowing into your webhook application when they occur.

This onboarding experience involves making calls to the Twilio Event Streams API using a Twilio Helper Library, twilio-cli, or cURL.

Note your Twilio Account SID and Auth Token from the Console, these will both be used to authenticate your calls.

Now we'll need to configure and create a sink using the Twilio Event Streams Sink API. A sink is the destination where events will be delivered.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function createSink() {
11
  const sink = await client.events.v1.sinks.create({
12
    description: "My Verify Events Webhook Sink",
13
    sinkConfiguration: {
14
      destination: "https://configureyourWebhookURLhere.com",
15
      method: "POST",
16
      batch_events: false,
17
    },
18
    sinkType: "webhook",
19
  });
20

21
  console.log(sink.dateCreated);
22
}
23

24
createSink();

1
{
2
  "status": "initialized",
3
  "sink_configuration": {
4
    "arn": "arn:aws:kinesis:us-east-1:111111111:stream/test",
5
    "role_arn": "arn:aws:iam::111111111:role/Role",
6
    "external_id": "1234567890"
7
  },
8
  "description": "My Verify Events Webhook Sink",
9
  "sid": "DGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
10
  "date_created": "2015-07-30T20:00:00Z",
11
  "sink_type": "webhook",
12
  "date_updated": "2015-07-30T20:00:00Z",
13
  "url": "https://events.twilio.com/v1/Sinks/DGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
14
  "links": {
15
    "sink_test": "https://events.twilio.com/v1/Sinks/DGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Test",
16
    "sink_validate": "https://events.twilio.com/v1/Sinks/DGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Validate"
17
  }
18
}

Make a note of the new sink's sid included in the response, it will be in the format DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX. You will use this information when you create a subscription in a later step.

The schema of an event defines how its information is organized. You can inspect the schema to explore the fields of an event type before using it, or use it to validate that the events you receive match their published schemas in production.

In this call, we're getting the version 1 schema of all available Verify events:

curl -X GET https://events-schemas.twilio.com/AccountSecurity.VerifyEventStreamEvent/1

Lastly, we need to create a subscription for your sink using the Twilio Event Streams Subscription API. A subscription defines which events will be sent to your sink.

Replace the SinkSid variable with your sink's SID. You can subscribe to one or more event types in a single subscription, check out the available Verify event types here. In this example, we'll subscribe to five different Verify event types.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function createSubscription() {
11
  const subscription = await client.events.v1.subscriptions.create({
12
    description: "My Verify Events Webhook Subscription",
13
    sinkSid: "DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
14
    types: [
15
      {
16
        type: "com.twilio.accountsecurity.verify.verification.approved",
17
      },
18
      {
19
        type: "com.twilio.accountsecurity.verify.verification.pending",
20
      },
21
      {
22
        type: "com.twilio.accountsecurity.verify.verification.canceled",
23
      },
24
      {
25
        type: "com.twilio.accountsecurity.verify.verification.expired",
26
      },
27
      {
28
        type: "com.twilio.accountsecurity.verify.verification.max-attempts-reached",
29
      },
30
    ],
31
  });
32

33
  console.log(subscription.accountSid);
34
}
35

36
createSubscription();

1
{
2
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
  "date_created": "2015-07-30T20:00:00Z",
4
  "date_updated": "2015-07-30T20:01:33Z",
5
  "sid": "DFaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6
  "sink_sid": "DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
7
  "description": "My Verify Events Webhook Subscription",
8
  "url": "https://events.twilio.com/v1/Subscriptions/DFaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
9
  "links": {
10
    "subscribed_events": "https://events.twilio.com/v1/Subscriptions/DFaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SubscribedEvents"
11
  }
12
}

That's it! Once the subscription is created, Verify events will start flowing into your webhook application when they occur.