# Realtime Secure Signed Webhook Streaming Export Integration

Secure Signed Webhook (SS Webhook) Streaming Export Integration enables real-time data delivery to external webhook endpoints with cryptographic signature verification as part of Treasure Data's activation workflows.

With this integration, you can securely send customer data to your webhook endpoints in real-time, with signatures to verify the authenticity and integrity of each request.

## Prerequisites

- Basic knowledge of Treasure Data
- Basic knowledge of webhook architecture and HTTP/HTTPS protocols
- Understanding of HMAC-SHA256 signature verification
- A publicly accessible HTTPS endpoint that can receive HTTP requests (Supported HTTP Methods: GET, POST, PUT, DELETE, and PATCH)
- Ability to implement signature verification logic on your webhook receiver


## Use Cases

The primary use case for this streaming integration is to incorporate it into a real-time activation workflow to:

- Send customer profile data to external systems in real-time
- Trigger downstream processes based on customer behavior
- Synchronize customer data with third-party applications
- Enable real-time personalization in external platforms


Here is an overview of how to configure that workflow to trigger a delivery:

1. Set up your webhook endpoint to receive HTTP requests with JSON payloads (POST is the default method, but other HTTP methods can be configured).
2. Implement signature verification logic using HMAC-SHA256 on your webhook receiver.
3. Create an authentication for this integration with your webhook URL and signing secret.
4. In a Real-time Journey, select this authentication for a new triggered activation.


## Requirements and Limitations

- The webhook endpoint must be accessible via HTTPS (TLS 1.2 or higher recommended).
- The endpoint must respond within 30 seconds to avoid timeout errors.
- Maximum payload size is 1MB per request.
- Rate limits depend on your infrastructure capacity.
- The signature is calculated using HMAC-SHA256 and sent in the `X-TD-Signature` header.
- Your webhook must return HTTP status codes 200-299 for successful processing.


## SS Webhook Streaming Export via Treasure Console

You must create and configure the data connection in Treasure Data. As part of the data connection, you provide authentication credentials to access the integration.

### Create Authentication

Perform the following steps to create a new authentication with a set of credentials.

1. Select Integrations Hub.
2. Select Catalog.
3. Search for your Integration in the Catalog; hover your mouse over the icon and select Create Authentication.


![SS Webhook connector tile in the Integrations Hub Catalog](/assets/ss-webhook-streaming-logo.dda6d183649c595141623038f8c57d55f748e65d1b3184d125904929bfc82a21.e33f8211.png)

1. Ensure that the Credentials tab is selected and then enter credential information for the integration.


### New Authentication Fields

![Authentication configuration screen showing the Webhook URL and Authentication Type fields](/assets/ss-webhook-streaming-authen.e7b49dd0377abcc0e83b9f169c8a216ca04bb7aed0703d88ae8ff7aa28a534ea.e33f8211.png)

| Parameter | Description |
|  --- | --- |
| URL Prefix | The base URL prefix of the webhook HTTPS endpoint that will receive the webhook requests. All triggered activations using this authentication must use URLs that start with this prefix. |
| Auth Type | Select the authorization type to secure your webhook endpoint. Supported types: **Basic Auth**, **Bearer Token**, **API Key**, **Treasure API Key**, **Custom Auth**, or **No Auth**. |


**Authentication Type Details:**

- **Basic Auth**: HTTP Basic Authentication using username and password
  - User Name: The username for authentication
  - Password: The password for authentication
- **Bearer Token**: OAuth 2.0 Bearer Token authentication
  - Bearer Token: The authentication token value
- **API Key**: Custom API key authentication
  - API Key Name: The name of the API key header or parameter
  - API Key: The API key value
- **Treasure API Key**: Treasure API key authentication
  - Uses your Treasure API key for authentication
- **Custom Auth**: Custom authentication headers
  - Configure custom authentication headers as needed
- **No Auth**: No authentication required
  - Use only for testing or publicly accessible endpoints


1. Select **Continue**.
2. Enter a name for your connection.
3. Select **Done.**


After configuring the SS Webhook Streaming integration, it is now available to be incorporated into real-time customer journey activations. See [Creating a Real-time Triggered Activation](/assets/triggeredactivation.66e546b8c4cc774c0bdd804d0d099b63cf12b1916181d85d7c715be95bd61810.9e7171ae.png).

### Real-time Triggered Activation

To create or update a triggered activation:

1. Select the triggered activation you want to configure ![](/assets/triggeredactivation.66e546b8c4cc774c0bdd804d0d099b63cf12b1916181d85d7c715be95bd61810.9e7171ae.png).
2. In the triggered activation window, select an activation from the Copy triggered activation from drop-down menu.
3. Enter a Triggered activation name.
4. Enter an Optional description of the activation.
5. From the Authentication drop-down menu, select the authentication the activation should use.


Depending on the type of authentication you choose, the details you will need to provide will vary. Refer to the integration-specific table below for more information.

![SS Webhook Output Streaming Activation Config](/assets/ss-webhook-streaming-triggered-activation.d28a845a4fe476054db8c0bba7368acd8568cca12bbd2ff2569c7fbb91086e6e.e33f8211.png)

1. Verify or provide the information required for the fields on the Details page.
2. After the Details are configured, select **Create** or **Update**.


### Integration Parameters

| Parameter | Values | Description |
|  --- | --- | --- |
| **HTTP Method** | optional, default POST | The HTTP method to use for the request. Supported methods: GET, POST, PUT, DELETE, PATCH |
| **URL** | required | The complete webhook API endpoint URL. Must start with the URL Prefix configured in the authentication |
| **Custom Headers** | optional - JSON Object | Additional HTTP headers to include in the request. You can add multiple headers with a maximum of 32 headers. The maximum size for each header key and value is 256 bytes each. Example: `{"Content-Type": "application/json", "X-Custom-Header": "value"}` |
| **Request Body** | required - JSON Object | The JSON payload structure to send to the webhook endpoint. |
| **Retry Limit** | optional, default 3 | Maximum number of retry attempts before giving up on failed requests |
| **Connection Timeout (Seconds)** | optional, default 30 | Maximum time in seconds to wait for establishing a connection to the webhook endpoint |
| **Read Timeout (Seconds)** | optional, default 30 | Maximum time in seconds to wait for reading the response from the webhook endpoint |
| **Write Timeout (Seconds)** | optional, default 30 | Maximum time in seconds to wait for sending the request payload to the webhook endpoint |


## Runtime Expressions and Crypto Functions

The SS Webhook integration supports dynamic runtime expressions and cryptographic functions that can be used in custom headers and request body.

### Runtime Expressions

Use these expressions to dynamically insert values at request time:

| Expression | Description | Example Output |
|  --- | --- | --- |
| `${unix_timestamp}` | Current Unix timestamp in seconds | `1709568000` |
| `${http_method}` | The HTTP method being used | `POST` |
| `${relative_path}` | The relative path of the URL (path after the domain) | `/api/webhook/events` |


**Example usage in Custom Headers:**


```json
{
  "X-Timestamp": "${unix_timestamp}",
  "X-Method": "${http_method}"
}
```

### Crypto Functions

Use these cryptographic functions to generate secure signatures for request authentication:

| Function | Description | Output Format |
|  --- | --- | --- |
| `${hmac_sha256_hex(secret, string)}` | Generates HMAC-SHA256 signature and returns as hexadecimal string | `a1b2c3d4e5...` |
| `${hmac_sha256_base64(secret, string)}` | Generates HMAC-SHA256 signature and returns as Base64-encoded string | `YTFiMmMzZD...` |


**Example usage for signature generation:**


```json
{
  "X-Signature": "${hmac_sha256_hex(my_secret_key, ${unix_timestamp}.${request_body})}",
  "X-Timestamp": "${unix_timestamp}"
}
```

This allows you to implement custom signature verification on your webhook endpoint similar to the Secure Signed Webhook pattern.

## Retry and Logging Logic

- The connector will retry to send the request when it gets the status code 429, 500, 502, 503, or 504.
- If the request is sent successfully before the **Retry Limit** is reached, the logging will show successfully.
- If the request still fails after reaching the **Retry Limit**, the connector will stop the job.
- We will see the error message and the status code in the client's activation table whenever the request sent fails.
- The **Retry Limit** can be configured in the Activation Config.


## Best Practices

- **Idempotency**: Design your webhook receiver to handle duplicate requests safely, as retries may occur.
- **Timeout Handling**: Ensure your webhook endpoint responds within 30 seconds. For long-running processes, acknowledge receipt immediately and process asynchronously.
- **Security**: Always verify the signature before processing the payload to prevent unauthorized requests.
- **Monitoring**: Implement logging and monitoring on your webhook endpoint to track successful deliveries and failures.
- **Error Handling**: Return appropriate HTTP status codes (200-299 for success, 4xx for client errors, 5xx for server errors).