Snowflake destination
Beta
Data Destinations is currently available as a Private Beta product and the information contained in this document is subject to change. Data Destinations is not a HIPAA Eligible Service or PCI compliant and should not be enabled in workflows that are subject to HIPAA or PCI. To learn more, see Private beta legal information.
Snowflake is a cloud data warehouse that lets you send event data directly into your Snowflake account for real-time analysis alongside your other business data.
- Category: Warehouse
- Release status: Beta
- Authentication: Key pair
- Regional availability: US1
Get early access to native destinations for data warehouses, observability tools, and event pipelines.
You can send all Event Types supported by Event Streams to Snowflake. There's no user-identifier restriction for this destination.
Before you set up a Snowflake destination, make sure you have:
- A Snowflake account.
- A Username: your Snowflake login name used for key-pair authentication.
- A Private Key (PEM): the PEM-encoded RSA private key paired with a public key registered on your Snowflake user, used for key-pair authentication.
- Your Snowflake Account Identifier (for example
xy12345.us-east-1ororgname-accountname). - An existing Database and Schema in Snowflake. Twilio verifies the schema exists before activating the destination but doesn't create it for you, so both must already exist and be visible to the role associated with your credentials.
- A Snowflake user whose default role has
USAGEon that database and schema, plusCREATE TABLEandCREATE PIPEon the schema. Twilio provisions your destination table and Snowpipe Streaming pipe under that role. The destination has no separate role setting.
Info
See Set up a destination for the full UI and Destinations API setup flow common to every destination type.
To create a Snowflake destination in the Twilio Console:
- From your Snowflake account, gather the settings listed in Destination settings.
- In the Twilio Console, go to Data > Data Destinations > Destinations > Add destination subscription.
- Complete the Add destination subscription wizard.
To create a Snowflake destination through the Destinations API, send a POST request to the Destinations endpoint and set destinationType to snowflake. For authentication and the other request body fields, see Create a destination.
POST "https://destinations.twilio.com/v1/ControlPlane/Destinations"
Set the config object in the request body as follows:
| Name | Type | Description |
|---|---|---|
account (Required) | string | Your Snowflake account identifier, for example xy12345.us-east-1 or orgname-accountname. |
credentials.credentialType (Required) | string | Set to KEY_PAIR. |
credentials.privateKey (Required) | string | Your PEM-encoded RSA private key for key-pair authentication. |
credentials.username (Required) | string | The Snowflake login name for key-pair authentication. |
database (Required) | string | The Snowflake database that holds the target tables. |
schema (Required) | string | The Snowflake schema that holds the target tables. |
The following example shows a request body. Replace the uppercase placeholder values with your own.
1{2"destinationType": "snowflake",3"name": "My Snowflake destination",4"config": {5"account": "ACCOUNT",6"credentials": {7"credentialType": "KEY_PAIR",8"privateKey": "PRIVATE_KEY",9"username": "USERNAME"10},11"database": "DATABASE",12"schema": "SCHEMA"13}14}
Use snowflake as the destinationType.
| Field | Description | Required | Default or choices |
|---|---|---|---|
| Username | Snowflake login name used for key-pair authentication. | Yes | Max 255 characters |
| Private Key (PEM) | PEM-encoded RSA private key used for key-pair authentication. Marked as sensitive, stored encrypted after entry. | Yes | N/A |
| Account Identifier | Snowflake account identifier (for example, xy12345.us-east-1 or orgname-accountname). | Yes | Max 63 characters |
| Database | The Snowflake database Twilio delivers events into. Can't be changed once the destination is created. | Yes | Max 255 characters |
| Schema | The Snowflake schema Twilio delivers events into. Can't be changed once the destination is created. | Yes | Max 255 characters |
Twilio authenticates to Snowflake by using key-pair JWT authentication. Twilio signs a JWT with your private key, and Snowflake validates it against the public key registered on your Snowflake user. Twilio stores your private key encrypted, and it never appears in event payloads. You can rotate your key pair at any time by updating the destination with a new private key.
Twilio delivers events to your table using
Snowpipe Streaming,
the Snowflake low-latency ingestion API, not bulk file loads or INSERT
statements. In most cases, Twilio streams through a single,
default Snowpipe Streaming pipe per table. For higher-throughput
subscriptions, Twilio can provision additional pipes on the same table (up
to 10) to increase ingestion parallelism. Twilio manages this pipe count
based on your subscription's volume. It isn't a setting you configure on the
destination.
The first time you save a subscription, Twilio automatically creates the
destination table TWILIO_EVENTS_<SUBSCRIPTION_ID> in your configured
database and schema. Table names are uppercase, and any . or - in the
subscription ID is replaced with _.
| Field | Snowflake column |
|---|---|
| Event ID | event_id |
| Event time | event_timestamp |
| Event type | event_type |
| Event payload | payload (JSON) |
When you save a Snowflake destination, Twilio authenticates with your key-pair credentials and confirms the configured database and schema are visible to your Snowflake role before marking the destination active. If validation fails, check that:
- Your Username and Private Key are correct and the public key is still registered on your Snowflake user.
- Your Account Identifier matches your Snowflake account exactly.
- Your Database and Schema already exist and are visible to the role associated with your credentials. Twilio doesn't create the schema for you.
Twilio doesn't currently offer a way to manually trigger a test event for this destination, from either the Console or the CLI. To confirm delivery is working, wait for a real event of a subscribed type to fire.
| Cause | What you'll see | Fix |
|---|---|---|
| Invalid or unregistered key pair | Validation fails with an authentication error | Re-check your username and private key, and confirm the matching public key is registered on your Snowflake user |
| Schema doesn't exist | Validation fails with a "schema not found" error | Create the schema in Snowflake, then retry |
| Wrong Account Identifier | Validation fails even with correct credentials | Confirm your account identifier format in Snowflake and update the destination |
Default role lacks CREATE TABLE or CREATE PIPE on the schema | Destination saves successfully, but the subscription fails to provision (reported as a resource error on the subscription) | Grant USAGE on the database/schema and CREATE TABLE, CREATE PIPE on the schema to the Snowflake user's default role, then retry |
| Snowpipe Streaming returns 410 (Gone) or a 5xx status | Delivery errors reported in the Debugger. Twilio resets the ingestion channel and retries | Retry is automatic. Sustained errors may indicate a transient Snowflake outage, so check the Snowflake status page |
| Snowpipe Streaming rejects the batch for another reason (4xx other than 410) | Delivery errors reported in the Debugger; not retried | Check your subscription's mapping and the target table's schema for a mismatch |
| The destination's per-subscription table state is missing or corrupted (internal error) | Delivery errors reported in the Debugger; not retried | Contact Twilio support. This indicates the destination wasn't fully provisioned |
If Twilio can't deliver events to your destination, Twilio sends an error notification to the Debugger (available in US1 region only). If Twilio continues to encounter delivery errors, Twilio notifies you every 20 minutes after the initial error.