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

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.

(information)

Info

An example of the sink_configurationobject 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"
_10
}

ParameterDescription
arnThe Amazon Resource Identifier(link takes you to an external page) for the Kinesis stream.
role_arnThe Amazon Resource Identifier for the AWS role that has write access to the Kineses stream specified arn.
external_idAn ID added to the role specified in role_arn which AWS requires in order to grant a third party access to a given resource. It helps prevent what is known as the Confused Deputy Problem(link takes you to an external page).

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>"
_10
}

ParameterDescription
destinationThe customers' url endpoint i.e http://example.org/webhook(link takes you to an external page)
methodThe HTTP method for updating the data on the webhook. The currently available options are GET and POST.

Here is an example of the sink_configuration object for a Segment Sink:


_10
"sink_configuration": {
_10
"write_key": "lwfOUDBL0VK33XstNWD3uJ7Eei2BdgY3"
_10
}

ParameterDescription
write_keySegment write key(link takes you to an external page) for the Segment source that you will use

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.

StatusDescription
initializedThe Sink has been created in the Event Streams API, but the connection still needs to be validated.
validatingA test event has been published to the Sink. The validation process has started, but has not yet been completed by the customer.
activeThe 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.

  1. First create a Sink resource of type Kinesis. The status of the Kinesis Sink will be initialized by default.
  2. 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.
  3. Check your Sink to see if the test event was successfully published. If so, this confirms that you've set up your Sink correctly.
  4. 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.


Sink Properties

sink-properties page anchor
Property nameTypePIIDescription
date_createdstring<date-time>
Not PII

The date that this Sink was created, given in ISO 8601 format.


date_updatedstring<date-time>

The date that this Sink was updated, given in ISO 8601 format.


descriptionstring

A human readable description for the Sink


sidSID<DG>

A 34 character string that uniquely identifies this Sink.

Pattern: ^DG[0-9a-fA-F]{32}$Min length: 34Max length: 34

sink_configurationobject

The information required for Twilio to connect to the provided Sink encoded as JSON.


sink_typeenum<string>

The Sink type. Can only be "kinesis" or "webhook" currently.

Possible values:
kinesiswebhooksegment

statusenum<string>

The Status of this Sink. One of initialized, validating, active or failed.

Possible values:
initializedvalidatingactivefailed

urlstring<uri>

The URL of this resource.


linksobject<uri-map>

Contains a dictionary of URL links to nested resources of this Sink.


POST https://events.twilio.com/v1/Sinks

Request body parameters

request-body-parameters page anchor
Property nameTypeRequiredPIIDescription
Descriptionstringrequired

A human readable description for the Sink This value should not contain PII.


SinkConfigurationobjectrequired

The information required for Twilio to connect to the provided Sink encoded as JSON.


SinkTypeenum<string>required

The Sink type. Can only be "kinesis" or "webhook" currently.

Possible values:
kinesiswebhooksegment

Create Sink

create-sink 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.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));

Output

_18
{
_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
},
_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
"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
}


GET https://events.twilio.com/v1/Sinks/{Sid}

Fetches a Sink configuration by its SID.

Property nameTypeRequiredPIIDescription
SidSID<DG>required

A 34 character string that uniquely identifies this Sink.

Pattern: ^DG[0-9a-fA-F]{32}$Min length: 34Max length: 34
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_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
_10
client.events.v1.sinks('DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.fetch()
_10
.then(sink => console.log(sink.sinkConfiguration));

Output

_18
{
_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
},
_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
"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
}


Read multiple Sink resources

read-multiple-sink-resources page anchor
GET https://events.twilio.com/v1/Sinks

Gets a list of all Sinks belonging to the account associated with the request. Supports pagination.

Property nameTypeRequiredPIIDescription
InUsebooleanOptional

A boolean query parameter filtering the results to return sinks used/not used by a subscription.


StatusstringOptional

A String query parameter filtering the results by status initialized, validating, active or failed.


PageSizeintegerOptional

How many resources to return in each list page. The default is 50, and the maximum is 1000.

Minimum: 1Maximum: 1000

PageintegerOptional

The page index. This value is simply for client state.

Minimum: 0

PageTokenstringOptional

The page token. This is provided by the API.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_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
_10
client.events.v1.sinks.list({limit: 20})
_10
.then(sinks => sinks.forEach(s => console.log(s.sid)));

Output

_67
{
_67
"sinks": [
_67
{
_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
},
_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
"links": {
_67
"sink_test": "https://events.twilio.com/v1/Sinks/DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Test",
_67
"sink_validate": "https://events.twilio.com/v1/Sinks/DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Validate"
_67
}
_67
},
_67
{
_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
},
_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
"links": {
_67
"sink_test": "https://events.twilio.com/v1/Sinks/DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Test",
_67
"sink_validate": "https://events.twilio.com/v1/Sinks/DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Validate"
_67
}
_67
},
_67
{
_67
"status": "active",
_67
"sink_configuration": {
_67
"destination": "http://example.org/webhook",
_67
"method": "POST",
_67
"batch_events": true
_67
},
_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
"links": {
_67
"sink_test": "https://events.twilio.com/v1/Sinks/DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Test",
_67
"sink_validate": "https://events.twilio.com/v1/Sinks/DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Validate"
_67
}
_67
}
_67
],
_67
"meta": {
_67
"page": 0,
_67
"page_size": 20,
_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",
_67
"key": "sinks"
_67
}
_67
}


POST https://events.twilio.com/v1/Sinks/{Sid}

Updates the description of a Sink

Property nameTypeRequiredPIIDescription
SidSID<DG>required

A 34 character string that uniquely identifies this Sink.

Pattern: ^DG[0-9a-fA-F]{32}$Min length: 34Max length: 34
Property nameTypeRequiredPIIDescription
Descriptionstringrequired

A human readable description for the Sink This value should not contain PII.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_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
_10
client.events.v1.sinks('DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.update({description: 'My Kinesis Sink'})
_10
.then(sink => console.log(sink.dateCreated));

Output

_18
{
_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
},
_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
"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
}


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.

Property nameTypeRequiredPIIDescription
SidSID<DG>required

A 34 character string that uniquely identifies this Sink.

Pattern: ^DG[0-9a-fA-F]{32}$Min length: 34Max length: 34
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_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
_10
client.events.v1.sinks('DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX').remove();


Rate this page: