Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Verify Events Onboarding Guide


(information)

Info

Verify Events is in Pilot!

This Verify feature is currently in the Pilot maturity stage, which means that we're actively looking for early-adopter customers to try it out and give feedback. That could be you!

Onboarding is now a self-serve process, follow this guide a step-by-step walkthrough.

Please note that Verify Events currently only supports SMS, WhatsApp, and Voice channels.

Verify Events allows you to access instantaneous, real-time information on the activity of your Verify Service by subscribing to a stream of Verify interactions.

In this guide we'll walk through the webhook onboarding process and explain the different methods you can use to integrate with Verify Events.

Not using a webhook? For more information on integrating using Amazon Kinesis, see Twilio Event Streams Kinesis Quickstart.

Click on the link to jump to that onboarding method:

  • Twilio Console
  • Events Streams API

Onboarding with Twilio Console

onboarding-with-twilio-console page anchor

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

Step 1: Setup

step-1-setup page anchor

If you haven't used Event Streams before, you'll want to pin it to your Twilio Console(link takes you to an external page) so it's easily accessible.

First navigate to the Twilio Console > Explore Products(link takes you to an external page) page. In the Developer tools product section, select the pin icon next to Event Streams to keep it pinned to your sidebar.

Step 2: Configure and create a sink

step-2-configure-and-create-a-sink page anchor

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

Step 3: (Optional) Validate sink connection

step-3-optional-validate-sink-connection page anchor

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.

Step 4: Configure and create a subscription

step-4-configure-and-create-a-subscription page anchor

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

Event Streams Create a New Subscription page showing the available Verify events.

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


Onboarding with Event Streams API

onboarding-with-event-streams-api page anchor

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(link takes you to an external page), these will both be used to authenticate your calls.

Step 2: Configure and create a sink

step-2--configure-and-create-a-sink-2 page anchor

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.

Create a New Sink

create-a-new-sink page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_18
// Download the helper library from https://www.twilio.com/docs/node/install
_18
// Find your Account SID and Auth Token at twilio.com/console
_18
// and set the environment variables. See http://twil.io/secure
_18
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_18
const authToken = process.env.TWILIO_AUTH_TOKEN;
_18
const client = require('twilio')(accountSid, authToken);
_18
_18
client.events.v1.sinks
_18
.create({
_18
description: 'My Verify Events Webhook Sink',
_18
sinkConfiguration: {
_18
destination: 'https://configureyourWebhookURLhere.com',
_18
method: 'POST',
_18
batch_events: false
_18
},
_18
sinkType: 'webhook'
_18
})
_18
.then(sink => console.log(sink.sid));

Output

_18
{
_18
"status": "initialized",
_18
"sink_configuration": {
_18
"destination": "https://configureyourWebhookURLhere.com",
_18
"method": "POST",
_18
"batch_events": false
_18
},
_18
"description": "My Verify Events Webhook Sink",
_18
"sid": "DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18
"date_created": "2015-07-30T20:00:00Z",
_18
"sink_type": "webhook",
_18
"date_updated": "2015-07-30T20:00:00Z",
_18
"url": "https://events.twilio.com/v1/Sinks/DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18
"links": {
_18
"sink_test": "https://events.twilio.com/v1/Sinks/DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Test",
_18
"sink_validate": "https://events.twilio.com/v1/Sinks/DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Validate"
_18
}
_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.

Step 3: Explore Verify event schemas

step-3-explore-verify-event-schemas page anchor

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:


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

Step 4: Configure and create a subscription

step-4--configure-and-create-a-subscription-2 page anchor

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.

Create a New Subscription

create-a-new-subscription page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_14
// Download the helper library from https://www.twilio.com/docs/node/install
_14
// Find your Account SID and Auth Token at twilio.com/console
_14
// and set the environment variables. See http://twil.io/secure
_14
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_14
const authToken = process.env.TWILIO_AUTH_TOKEN;
_14
const client = require('twilio')(accountSid, authToken);
_14
_14
client.events.v1.subscriptions
_14
.create({
_14
description: 'My Verify Events Webhook Subscription',
_14
sinkSid: 'DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
_14
types: [{'type': 'com.twilio.accountsecurity.verify.verification.approved'}, {'type': 'com.twilio.accountsecurity.verify.verification.pending'}, {'type': 'com.twilio.accountsecurity.verify.verification.canceled'}, {'type': 'com.twilio.accountsecurity.verify.verification.expired'}, {'type': 'com.twilio.accountsecurity.verify.verification.max-attempts-reached'}]
_14
})
_14
.then(subscription => console.log(subscription.sid));

Output

_12
{
_12
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_12
"date_created": "2015-07-30T20:00:00Z",
_12
"date_updated": "2015-07-30T20:01:33Z",
_12
"sid": "DFXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_12
"sink_sid": "DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_12
"description": "My Verify Events Webhook Subscription",
_12
"url": "https://events.twilio.com/v1/Subscriptions/DFXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_12
"links": {
_12
"subscribed_events": "https://events.twilio.com/v1/Subscriptions/DFXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SubscribedEvents"
_12
}
_12
}

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


Rate this page: