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.
Not seeing a sink type you would like to configure? Submit a sink type request.
An example of the sink_configuration object for a Kinesis Sink:
"sink_configuration": {
"arn": "arn:aws:kinesis:us-east-1:111111111:stream/test",
"role_arn": "arn:aws:iam::111111111:role/Role",
"external_id": "a secret value here"
}| 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:
"sink_configuration": {
"destination": "http://example.org/webhook",
"method": "<POST|GET>",
"batch_events": <true|false>
}| 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. |
batch_events |
false if you want to receive single events and true if you want events sent in batches. Batched events currently have a 64kB data limit. |
Here is an example of the sink_configuration object for a Segment Sink:
"sink_configuration": {
"write_key": "lwfOUDBL0VK33XstNWD3uJ7Eei2BdgY3"
}| Parameter | Description |
write_key |
Segment write key 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.
| 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
initializedby default. - Create a Sink Test Resource using your new Sink. The URL for this POST request is provided in the new Sink’s
linksobject. 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_idand create a Sink Validate resource. The URL for this POST request is provided in the Sink’slinksobject. This will let Twilio know that you successfully configured the Sink, and will toggle the Sink’s status toactive.
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
| Resource Properties in REST API format | |
|---|---|
date_created
|
The date that this Sink was created, given in ISO 8601 format. |
date_updated
|
The date that this Sink was updated, given in ISO 8601 format. |
description
|
A human readable description for the Sink |
sid
|
A 34 character string that uniquely identifies this Sink. |
sink_configuration
|
The information required for Twilio to connect to the provided Sink encoded as JSON. |
sink_type
|
The Sink type. Can only be "kinesis" or "webhook" currently. |
status
|
The Status of this Sink. One of |
url
|
The URL of this resource. |
links
|
Contains a dictionary of URL links to nested resources of this Sink. |
Create a Sink resource
https://events.twilio.com/v1/Sinks
Parameters
| Parameters in REST API format | |
|---|---|
description
Required
|
A human readable description for the Sink This value should not contain PII. |
sink_configuration
Required
|
The information required for Twilio to connect to the provided Sink encoded as JSON. |
sink_type
Required
|
The Sink type. Can only be "kinesis" or "webhook" currently. |
Example 1
Fetch a Sink resource
https://events.twilio.com/v1/Sinks/{Sid}
Fetches a Sink configuration by its SID.
Parameters
| Parameters in REST API format | |
|---|---|
sid
Path
|
A 34 character string that uniquely identifies this Sink. |
Example 1
Read multiple Sink resources
https://events.twilio.com/v1/Sinks
Gets a list of all Sinks belonging to the account associated with the request. Supports pagination.
Parameters
| Parameters in REST API format | |
|---|---|
in_use
Optional
|
A boolean query parameter filtering the results to return sinks used/not used by a subscription. |
status
Optional
|
A String query parameter filtering the results by status |
Example 1
Update Sink
https://events.twilio.com/v1/Sinks/{Sid}
Updates the description of a Sink
Parameters
| Parameters in REST API format | |
|---|---|
sid
Path
|
A 34 character string that uniquely identifies this Sink. |
description
Required
|
A human readable description for the Sink This value should not contain PII. |
Example 1
Delete a Sink resource
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.
Parameters
| Parameters in REST API format | |
|---|---|
sid
Path
|
A 34 character string that uniquely identifies this Sink. |
Example 1
Need some help?
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.
