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

Not seeing a sink type you would like to configure? Submit a sink type request.

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}

Parameter	Description
`arn`	The Amazon Resource Identifier for the Kinesis stream.
`role_arn`	The Amazon Resource Identifier for the AWS role that has write access to the Kineses stream specified `arn`.
`external_id`	An 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.

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}

Parameter	Description
`destination`	The customers' url endpoint i.e http://example.org/webhook
`method`	The 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:

1"sink_configuration": { 
2    "write_key": "lwfOUDBL0VK33XstNWD3uJ7Eei2BdgY3"
3}

Parameter	Description
`write_key`	Segment write key for the Segment source that you will use

Sink Properties

Property nameTypeRequiredDescriptionChild properties

date_createdstring<date-time>Optional

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

date_updatedstring<date-time>Optional

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

descriptionstringOptional

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

sink_configurationobjectOptional

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

sink_typeenum<string>Optional

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

Possible values:

kinesiswebhooksegment

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.

Create a Sink resource

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

Request body parameters

Encoding type:application/x-www-form-urlencoded

SchemaExample

Property nameTypeRequiredDescriptionChild properties

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

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async 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
24createSink();

Output

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}

Fetch a Sink resource

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

Fetches a Sink configuration by its SID.

Path parameters

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

Fetch Sink

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function fetchSink() {
11  const sink = await client.events.v1
12    .sinks("DGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13    .fetch();
14
15  console.log(sink.sinkConfiguration);
16}
17
18fetchSink();

Output

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

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

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

Query parameters

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.

Read Sink

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listSink() {
11  const sinks = await client.events.v1.sinks.list({ limit: 20 });
12
13  sinks.forEach((s) => console.log(s.dateCreated));
14}
15
16listSink();

Output

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}

Update Sink

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

Updates the description of a Sink

Path parameters

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

Request body parameters

Encoding type:application/x-www-form-urlencoded

SchemaExample

Property nameTypeRequiredDescriptionChild properties

Descriptionstringrequired

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

Update Sink

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async 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
18updateSink();

Output

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 a Sink resource

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.

Path parameters

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

Delete Sink

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function deleteSink() {
11  await client.events.v1.sinks("DGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa").remove();
12}
13
14deleteSink();