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 page and store it in your application. For details, see 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

   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

   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 page. The Status column returns to a successful state after a later successful delivery.