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

dateCreatedstring<date-time>

Optional

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

sinkConfigurationobject

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.

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

descriptionstring

required

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

sinkConfigurationobject

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 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();

Response

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();

Response

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

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.

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();

Response

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

descriptionstring

required

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();

Response

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();