> This page is for version v1.3 (default).
> For other versions, use one of these documentation indexes:
> - v1.3 (default): https://docs.twelvelabs.io/v1.3/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.twelvelabs.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.twelvelabs.io/_mcp/server.

# Requirements for processing notifications

> Set up a publicly accessible endpoint, verify signatures, and respond with a 2xx status code.

To receive notifications, your endpoint must be publicly accessible. For each incoming notification, complete the following:

# 1. Validate the integrity of a notification

Each notification carries a `TL-Signature` header. Verify it before acting on the payload.

The header has two parts:

* `t`: A Unix timestamp for the moment the platform sent the notification.
* `v1`: An HMAC-SHA256 signature computed over the timestamp and the raw request body.

To verify the signature:

1. Retrieve your secret key from the [Webhooks](https://playground.twelvelabs.io/dashboard/integrations/webhooks) page and store it in your application. For details, see [Retrieve your secret key](/v1.3/docs/advanced/webhooks/manage#retrieve-your-secret-key).

2. Split the `TL-Signature` header on the comma (`,`) character. Extract the `t` and `v1` values.

3. Build the signed payload. Concatenate the timestamp and the raw request body, separated by a dot (`.`). Use the raw request body. Parsing the body first changes the signature and the check fails.

   **`Go`**

   ```go Go
   timestampFromHeader = "1659342128"
   body = '{"name":"test"}'
   signedPayload = timestampFromHeader + "." + body // 1659342128.{"name":"test"}
   ```

4. Compute an HMAC-SHA256 over the signed payload, using your secret key as the HMAC key.

   **`Go`**

   ```go Go
   func generateHmacSha256Signature(secret, payload string) string {
      h := hmac.New(sha256.New, []byte(secret))
      h.Write([]byte(payload))
      return hex.EncodeToString(h.Sum(nil))
   }
   ```

5. Compare the signature you computed with the `v1` value from the header. If they match, the notification came from TwelveLabs.

6. *(Optional)* Compare the `t` value with the current time. TwelveLabs recommends rejecting notifications older than five minutes.

# 2. Respond with a 2xx status code

Return a `2xx` status code for every notification. Any other status code is a delivery failure, and the **Status** column on the Dashboard shows **Failed**.

## Retry policy

The platform retries a delivery only when the endpoint responds with a `5xx` status code. Up to three attempts are made in total: the initial delivery, a second attempt after 1 second, and a third attempt after another 2 seconds. Each attempt has a 5-second timeout, so a delivery that receives `5xx` responses through every attempt takes up to about 18 seconds.

Final `3xx` and `4xx` responses (including `429`), network errors, and request timeouts are not retried.

Retries repeat the request body and the `id` field, so you can use the `id` value to deduplicate. The `TL-Signature` header is generated again for each attempt, so its timestamp and signature can differ between attempts.

## After a delivery fails

The platform does not queue the notification for later redelivery, and you cannot retrieve it through an API. Retrieve the analysis task and inspect its `webhooks` field to see per-endpoint delivery state (`delivered`, `attempts`, `last_error`).

Repeated failures do not automatically disable the endpoint. Future notifications continue to be sent until you disable or remove the endpoint on the [Webhooks](https://playground.twelvelabs.io/dashboard/integrations/webhooks) page. The **Status** column returns to a successful state after a later successful delivery.