Skip to contentSkip to navigationSkip to topbar
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:

1
"sink_configuration": {
2
"arn": "arn:aws:kinesis:us-east-1:111111111:stream/test",
3
"role_arn": "arn:aws:iam::111111111:role/Role",
4
"external_id": "a secret value here"
5
}
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:

1
"sink_configuration": {
2
"destination": "http://example.org/webhook",
3
"method": "<POST|GET>"
4
}
ParameterDescriptionAccepted valuesExample
destinationThe customers' url endpointWebhook URLhttp://example.org/webhook
methodThe HTTP method for updating the data on the webhook.GET , POST

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

1
"sink_configuration": {
2
"write_key": "lwfOUDBL0VK33XstNWD3uJ7Eei2BdgY3"
3
}
ParameterDescription
write_keySegment write key(link takes you to an external page) for the Segment source that you will use

Sink Properties

sink-properties page anchor
Property nameTypeRequiredDescriptionChild properties
dateCreatedstring<date-time>

Optional

Not PII

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


dateUpdatedstring<date-time>

Optional

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


descriptionstring

Optional

A human readable description for the Sink


sidSID<DG>

Optional

A 34 character string that uniquely identifies this Sink.

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

sinkConfiguration

Optional

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


sinkTypeenum<string>

Optional

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

Possible values:
kinesiswebhooksegmentemail

statusenum<string>

Optional

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

Possible values:
initializedvalidatingactivefailed

urlstring<uri>

Optional

The URL of this resource.


linksobject<uri-map>

Optional

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
Encoding type:application/x-www-form-urlencoded
SchemaExample
Property nameTypeRequiredDescriptionChild properties
descriptionstring
required

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


sinkConfiguration
required

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:
kinesiswebhooksegmentemail
Create SinkLink to code sample: Create Sink
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 Kinesis Sink",
13
sinkConfiguration: {
14
arn: "arn:aws:kinesis:us-east-1:111111111:stream/test",
15
role_arn: "arn:aws:iam::111111111:role/Role",
16
external_id: "1234567890",
17
},
18
sinkType: "kinesis",
19
});
20
21
console.log(sink.dateCreated);
22
}
23
24
createSink();

Response

Note: This shows the raw API response from Twilio. Responses from SDKs (Java, Python, etc.) may look a little different.
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 Kinesis Sink",
9
"sid": "DGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
10
"date_created": "2015-07-30T20:00:00Z",
11
"sink_type": "kinesis",
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
}

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
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 fetchSink() {
11
const sink = await client.events.v1
12
.sinks("DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13
.fetch();
14
15
console.log(sink.sinkConfiguration);
16
}
17
18
fetchSink();

Response

Note: This shows the raw API response from Twilio. Responses from SDKs (Java, Python, etc.) may look a little different.
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": "A Sink",
9
"sid": "DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
10
"date_created": "2015-07-30T20:00:00Z",
11
"sink_type": "kinesis",
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
}

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
inUseboolean

Optional

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


statusstring

Optional

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


pageSizeinteger<int64>

Optional

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

Minimum: 1Maximum: 1000

pageinteger

Optional

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

Minimum: 0

pageTokenstring

Optional

The page token. This is provided by the API.

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 listSink() {
11
const sinks = await client.events.v1.sinks.list({ limit: 20 });
12
13
sinks.forEach((s) => console.log(s.dateCreated));
14
}
15
16
listSink();

Response

Note: This shows the raw API response from Twilio. Responses from SDKs (Java, Python, etc.) may look a little different.
1
{
2
"sinks": [
3
{
4
"status": "initialized",
5
"sink_configuration": {
6
"arn": "arn:aws:kinesis:us-east-1:111111111:stream/test",
7
"role_arn": "arn:aws:iam::111111111:role/Role",
8
"external_id": "1234567890"
9
},
10
"description": "A Sink",
11
"sid": "DGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
12
"date_created": "2015-07-30T19:00:00Z",
13
"sink_type": "kinesis",
14
"date_updated": "2015-07-30T19:00:00Z",
15
"url": "https://events.twilio.com/v1/Sinks/DGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
16
"links": {
17
"sink_test": "https://events.twilio.com/v1/Sinks/DGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Test",
18
"sink_validate": "https://events.twilio.com/v1/Sinks/DGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Validate"
19
}
20
},
21
{
22
"status": "initialized",
23
"sink_configuration": {
24
"arn": "arn:aws:kinesis:us-east-1:222222222:stream/test",
25
"role_arn": "arn:aws:iam::111111111:role/Role",
26
"external_id": "1234567890"
27
},
28
"description": "ANOTHER Sink",
29
"sid": "DGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaab",
30
"date_created": "2015-07-30T20:00:00Z",
31
"sink_type": "kinesis",
32
"date_updated": "2015-07-30T20:00:00Z",
33
"url": "https://events.twilio.com/v1/Sinks/DGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaab",
34
"links": {
35
"sink_test": "https://events.twilio.com/v1/Sinks/DGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaab/Test",
36
"sink_validate": "https://events.twilio.com/v1/Sinks/DGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaab/Validate"
37
}
38
},
39
{
40
"status": "active",
41
"sink_configuration": {
42
"destination": "http://example.org/webhook",
43
"method": "POST",
44
"batch_events": true
45
},
46
"description": "A webhook Sink",
47
"sid": "DGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaac",
48
"date_created": "2015-07-30T21:00:00Z",
49
"sink_type": "webhook",
50
"date_updated": "2015-07-30T21:00:00Z",
51
"url": "https://events.twilio.com/v1/Sinks/DGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaac",
52
"links": {
53
"sink_test": "https://events.twilio.com/v1/Sinks/DGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaac/Test",
54
"sink_validate": "https://events.twilio.com/v1/Sinks/DGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaac/Validate"
55
}
56
}
57
],
58
"meta": {
59
"page": 0,
60
"page_size": 20,
61
"first_page_url": "https://events.twilio.com/v1/Sinks?PageSize=20&Page=0",
62
"previous_page_url": null,
63
"url": "https://events.twilio.com/v1/Sinks?PageSize=20&Page=0",
64
"next_page_url": null,
65
"key": "sinks"
66
}
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
Encoding type:application/x-www-form-urlencoded
SchemaExample
Property nameTypeRequiredDescriptionChild properties
descriptionstring
required

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

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 updateSink() {
11
const sink = await client.events.v1
12
.sinks("DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13
.update({ description: "My Kinesis Sink" });
14
15
console.log(sink.dateCreated);
16
}
17
18
updateSink();

Response

Note: This shows the raw API response from Twilio. Responses from SDKs (Java, Python, etc.) may look a little different.
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 Kinesis Sink",
9
"sid": "DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
10
"date_created": "2015-07-30T20:00:00Z",
11
"sink_type": "kinesis",
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
}

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
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 deleteSink() {
11
await client.events.v1.sinks("DGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa").remove();
12
}
13
14
deleteSink();