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> Not PIIThe date that this Sink was created, given in ISO 8601 format.
date_updated
type: string<DATE TIME> Not PIIThe date that this Sink was updated, given in ISO 8601 format.
A human readable description for the Sink
A 34 character string that uniquely identifies this Sink.
sink_configuration
type: object Not PIIThe information required for Twilio to connect to the provided Sink encoded as JSON.
The Sink type. Can only be "kinesis" or "webhook" currently.
Possible values:
kinesis
webhook
segment
The Status of this Sink. One of initialized
, validating
, active
or failed
.
Possible values:
initialized
validating
active
failed
The URL of this resource.
Contains a dictionary of URL links to nested resources of this Sink.
POST https://events.twilio.com/v1/Sinks
Request body parameters Required
A human readable description for the Sink This value should not contain PII.
SinkConfiguration
type: object Not PIIRequired
The information required for Twilio to connect to the provided Sink encoded as JSON.
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
_14 const accountSid = process.env.TWILIO_ACCOUNT_SID;
_14 const authToken = process.env.TWILIO_AUTH_TOKEN;
_14 const client = require('twilio')(accountSid, authToken);
_14 client.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 Path Parameter
A 34 character string that uniquely identifies this Sink.
_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
_10 const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10 const authToken = process.env.TWILIO_AUTH_TOKEN;
_10 const client = require('twilio')(accountSid, authToken);
_10 client.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 Query Parameter
A boolean query parameter filtering the results to return sinks used/not used by a subscription.
Query Parameter
A String query parameter filtering the results by status initialized
, validating
, active
or failed
.
Query Parameter
How many resources to return in each list page. The default is 50, and the maximum is 1000.
Query Parameter
The page index. This value is simply for client state.
Query Parameter
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
_10 const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10 const authToken = process.env.TWILIO_AUTH_TOKEN;
_10 const client = require('twilio')(accountSid, authToken);
_10 client.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 Path Parameter
A 34 character string that uniquely identifies this Sink.
Request body parameters Required
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
_10 const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10 const authToken = process.env.TWILIO_AUTH_TOKEN;
_10 const client = require('twilio')(accountSid, authToken);
_10 client.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 Path Parameter
A 34 character string that uniquely identifies this Sink.
_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
_10 const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10 const authToken = process.env.TWILIO_AUTH_TOKEN;
_10 const client = require('twilio')(accountSid, authToken);
_10 client.events.v1.sinks('DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX').remove();