Sink Resource
Sinks are the destinations to which events selected in a subscription will be delivered. Each sink has a sink_type
property. At this time, the Sink resource supports three types: AWS Kinesis indicated by the value kinesis
, Webhooks indicated by the value webhook
, and Segment indicated by the value segment
. Each Sink has a sink_configuration
property which expresses its set up.
An example of the sink_configuration
object for a Kinesis Sink:
_10"sink_configuration": {
_10 "arn": "arn:aws:kinesis:us-east-1:111111111:stream/test",
_10 "role_arn": "arn:aws:iam::111111111:role/Role",
_10 "external_id": "a secret value here"
Here is an example of the sink_configuration
object for a Webhook Sink:
_10"sink_configuration": {
_10 "destination": "http://example.org/webhook",
_10 "method": "<POST|GET>"
Here is an example of the sink_configuration
object for a Segment Sink:
_10"sink_configuration": {
_10 "write_key": "lwfOUDBL0VK33XstNWD3uJ7Eei2BdgY3"
Each Sink also has a status
property. The value of this property will be one of initialized
, validating
, and active
. To receive events, a Sink must be in active
status.
Status | Description |
---|
initialized | The Sink has been created in the Event Streams API, but the connection still needs to be validated. |
validating | A test event has been published to the Sink. The validation process has started, but has not yet been completed by the customer. |
active | The sink has been validated or validation is not required. Events can only be delivered to Sinks with active status. |
When a new Kinesis Sink is created, its default status
is initialized
. To make it active
, you need to complete the following steps.
-
First create a Sink resource of type Kinesis. The status of the Kinesis Sink will be
initialized
by default.
-
Create a
Sink Test Resource
using your new Sink. The URL for this POST request is provided in the new Sink's
links
object. This will publish a test event to your Sink.
-
Check your Sink to see if the test event was successfully published. If so, this confirms that you've set up your Sink correctly.
-
If the test was successful, retrieve the
test_id
and create a
Sink Validate resource
. The URL for this POST request is provided in the Sink's
links
object. This will let Twilio know that you successfully configured the Sink, and will toggle the Sink's status to
active
.
Webhook and Segment Sinks are active
by default, so you do not have to validate them. However, if you choose to validate them, you can still do so with the Test and Validate resources mentioned above.
Resource properties
date_created
type: string<date-time>
The date that this Sink was created, given in ISO 8601 format.
date_updated
type: string<date-time>
The date that this Sink was updated, given in ISO 8601 format.
description
type: string
A human readable description for the Sink
sid
type: SID<DG>
A 34 character string that uniquely identifies this Sink.
Pattern:
^DG[0-9a-fA-F]{32}$
sink_configuration
type: object
The information required for Twilio to connect to the provided Sink encoded as JSON.
sink_type
type: enum<string>
The Sink type. Can only be "kinesis" or "webhook" currently.
Possible values:
kinesis
webhook
segment
status
type: enum<string>
The Status of this Sink. One of initialized
, validating
, active
or failed
.
Possible values:
initialized
validating
active
failed
url
type: string<uri>
The URL of this resource.
links
type: object<uri-map>
Contains a dictionary of URL links to nested resources of this Sink.
POST https://events.twilio.com/v1/Sinks
Request body parameters
Description
type: stringRequired
A human readable description for the Sink This value should not contain PII.
SinkConfiguration
type: objectRequired
The information required for Twilio to connect to the provided Sink encoded as JSON.
SinkType
type: enum<string>Required
The Sink type. Can only be "kinesis" or "webhook" currently.
Possible values:
kinesis
webhook
segment
_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
_14const accountSid = process.env.TWILIO_ACCOUNT_SID;
_14const authToken = process.env.TWILIO_AUTH_TOKEN;
_14const client = require('twilio')(accountSid, authToken);
_14client.events.v1.sinks
_14 .create({description: 'My Kinesis Sink', sinkConfiguration: {
_14 arn: 'arn:aws:kinesis:us-east-1:111111111:stream/test',
_14 role_arn: 'arn:aws:iam::111111111:role/Role',
_14 external_id: '1234567890'
_14 }, sinkType: 'kinesis'})
_14 .then(sink => console.log(sink.sid));
_18 "status": "initialized",
_18 "sink_configuration": {
_18 "arn": "arn:aws:kinesis:us-east-1:111111111:stream/test",
_18 "role_arn": "arn:aws:iam::111111111:role/Role",
_18 "external_id": "1234567890"
_18 "description": "My Kinesis Sink",
_18 "sid": "DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18 "date_created": "2015-07-30T20:00:00Z",
_18 "sink_type": "kinesis",
_18 "date_updated": "2015-07-30T20:00:00Z",
_18 "url": "https://events.twilio.com/v1/Sinks/DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18 "sink_test": "https://events.twilio.com/v1/Sinks/DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Test",
_18 "sink_validate": "https://events.twilio.com/v1/Sinks/DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Validate"
GET https://events.twilio.com/v1/Sinks/{Sid}
Fetches a Sink configuration by its SID.
URI parameters
Sid
type: SID<DG>
A 34 character string that uniquely identifies this Sink.
Pattern:
^DG[0-9a-fA-F]{32}$
_10// Download the helper library from https://www.twilio.com/docs/node/install
_10// Find your Account SID and Auth Token at twilio.com/console
_10// and set the environment variables. See http://twil.io/secure
_10const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10const authToken = process.env.TWILIO_AUTH_TOKEN;
_10const client = require('twilio')(accountSid, authToken);
_10client.events.v1.sinks('DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10 .then(sink => console.log(sink.sinkConfiguration));
_18 "status": "initialized",
_18 "sink_configuration": {
_18 "arn": "arn:aws:kinesis:us-east-1:111111111:stream/test",
_18 "role_arn": "arn:aws:iam::111111111:role/Role",
_18 "external_id": "1234567890"
_18 "description": "A Sink",
_18 "sid": "DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18 "date_created": "2015-07-30T20:00:00Z",
_18 "sink_type": "kinesis",
_18 "date_updated": "2015-07-30T20:00:00Z",
_18 "url": "https://events.twilio.com/v1/Sinks/DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18 "sink_test": "https://events.twilio.com/v1/Sinks/DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Test",
_18 "sink_validate": "https://events.twilio.com/v1/Sinks/DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Validate"
GET https://events.twilio.com/v1/Sinks
Gets a list of all Sinks belonging to the account associated with the request. Supports pagination.
URI parameters
InUse
type: boolean
A boolean query parameter filtering the results to return sinks used/not used by a subscription.
Status
type: string
A String query parameter filtering the results by status initialized
, validating
, active
or failed
.
PageSize
type: integer
How many resources to return in each list page. The default is 50, and the maximum is 1000.
Page
type: integer
The page index. This value is simply for client state.
PageToken
type: string
The page token. This is provided by the API.
_10// Download the helper library from https://www.twilio.com/docs/node/install
_10// Find your Account SID and Auth Token at twilio.com/console
_10// and set the environment variables. See http://twil.io/secure
_10const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10const authToken = process.env.TWILIO_AUTH_TOKEN;
_10const client = require('twilio')(accountSid, authToken);
_10client.events.v1.sinks.list({limit: 20})
_10 .then(sinks => sinks.forEach(s => console.log(s.sid)));
_67 "status": "initialized",
_67 "sink_configuration": {
_67 "arn": "arn:aws:kinesis:us-east-1:111111111:stream/test",
_67 "role_arn": "arn:aws:iam::111111111:role/Role",
_67 "external_id": "1234567890"
_67 "description": "A Sink",
_67 "sid": "DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_67 "date_created": "2015-07-30T19:00:00Z",
_67 "sink_type": "kinesis",
_67 "date_updated": "2015-07-30T19:00:00Z",
_67 "url": "https://events.twilio.com/v1/Sinks/DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_67 "sink_test": "https://events.twilio.com/v1/Sinks/DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Test",
_67 "sink_validate": "https://events.twilio.com/v1/Sinks/DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Validate"
_67 "status": "initialized",
_67 "sink_configuration": {
_67 "arn": "arn:aws:kinesis:us-east-1:222222222:stream/test",
_67 "role_arn": "arn:aws:iam::111111111:role/Role",
_67 "external_id": "1234567890"
_67 "description": "ANOTHER Sink",
_67 "sid": "DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_67 "date_created": "2015-07-30T20:00:00Z",
_67 "sink_type": "kinesis",
_67 "date_updated": "2015-07-30T20:00:00Z",
_67 "url": "https://events.twilio.com/v1/Sinks/DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_67 "sink_test": "https://events.twilio.com/v1/Sinks/DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Test",
_67 "sink_validate": "https://events.twilio.com/v1/Sinks/DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Validate"
_67 "sink_configuration": {
_67 "destination": "http://example.org/webhook",
_67 "description": "A webhook Sink",
_67 "sid": "DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_67 "date_created": "2015-07-30T21:00:00Z",
_67 "sink_type": "webhook",
_67 "date_updated": "2015-07-30T21:00:00Z",
_67 "url": "https://events.twilio.com/v1/Sinks/DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_67 "sink_test": "https://events.twilio.com/v1/Sinks/DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Test",
_67 "sink_validate": "https://events.twilio.com/v1/Sinks/DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Validate"
_67 "first_page_url": "https://events.twilio.com/v1/Sinks?PageSize=20&Page=0",
_67 "previous_page_url": "https://events.twilio.com/v1/Sinks?PageSize=20&Page=0",
_67 "url": "https://events.twilio.com/v1/Sinks?PageSize=20&Page=0",
_67 "next_page_url": "https://events.twilio.com/v1/Sinks?PageSize=20&Page=1",
POST https://events.twilio.com/v1/Sinks/{Sid}
Updates the description of a Sink
URI parameters
Sid
type: SID<DG>
A 34 character string that uniquely identifies this Sink.
Pattern:
^DG[0-9a-fA-F]{32}$
Request body parameters
Description
type: stringRequired
A human readable description for the Sink This value should not contain PII.
_10// Download the helper library from https://www.twilio.com/docs/node/install
_10// Find your Account SID and Auth Token at twilio.com/console
_10// and set the environment variables. See http://twil.io/secure
_10const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10const authToken = process.env.TWILIO_AUTH_TOKEN;
_10const client = require('twilio')(accountSid, authToken);
_10client.events.v1.sinks('DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10 .update({description: 'My Kinesis Sink'})
_10 .then(sink => console.log(sink.dateCreated));
_18 "status": "initialized",
_18 "sink_configuration": {
_18 "arn": "arn:aws:kinesis:us-east-1:111111111:stream/test",
_18 "role_arn": "arn:aws:iam::111111111:role/Role",
_18 "external_id": "1234567890"
_18 "description": "My Kinesis Sink",
_18 "sid": "DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18 "date_created": "2015-07-30T20:00:00Z",
_18 "sink_type": "kinesis",
_18 "date_updated": "2015-07-30T20:00:00Z",
_18 "url": "https://events.twilio.com/v1/Sinks/DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18 "sink_test": "https://events.twilio.com/v1/Sinks/DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Test",
_18 "sink_validate": "https://events.twilio.com/v1/Sinks/DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Validate"
DELETE https://events.twilio.com/v1/Sinks/{Sid}
Deletes the Sink with the specified SID. If the Sink has a Subscription associated with it, the Subscription must be deleted first in order to delete the Sink.
URI parameters
Sid
type: SID<DG>
A 34 character string that uniquely identifies this Sink.
Pattern:
^DG[0-9a-fA-F]{32}$
_10// Download the helper library from https://www.twilio.com/docs/node/install
_10// Find your Account SID and Auth Token at twilio.com/console
_10// and set the environment variables. See http://twil.io/secure
_10const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10const authToken = process.env.TWILIO_AUTH_TOKEN;
_10const client = require('twilio')(accountSid, authToken);
_10client.events.v1.sinks('DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX').remove();