To receive notifications, ensure that the URL of your endpoint is publicly accessible. Once your application receives notifications, it must perform at least the following steps:

1. Validate the integrity of an event

Twelve Labs includes a unique header named TL-Signature in each POST request. The header is composed of the following parts:

• t : A Unix timestamp representing the time when the platform has sent the notification
• v1 : A signature generated uniquely for each webhook event, using HMAC with SHA-256

To validate the signature and verify that the event was sent by Twelve Labs:

1. The platform uses a secret key to sign each POST request. You must retrieve it from the Dashboard page by following the steps in the Retrieve your secret key section and then store it in your application.

2. Extract the t and v1 fields. Split the TL-Signature header, using the comma (,) character as a separator.

3. Generate a signed payload. Concatenate the timestamp retrieved from the header and the raw request body, using the dot ( .) character as a separator.

   Note that you must use the raw request body. Do not parse the request body or else the validation will fail.
   Example:

   Go

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

4. Create a HmacSha256 signature using the secret key you've retrieved from the Dashboard page for the HMAC key and the signed payload as payload.

   The following example shows how you can generate a signature in 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 computed in the previous step with the signature provided in the header. If the signatures match, it means that Twelve Labs is the sender of the notification.

6. (Optional) As an additional security measure, you can also compare the timestamp received in the t field to the current time. Twelve Labs suggest you consider valid all the requests for which the time difference is less than five minutes.

2. Respond with a 2xx status code

For each notification that the platform sends to your webhook, it must return a 2xx status code to indicate that the notification has successfully been delivered. A different response code will be treated by the platform as a failure, and the status will show as Failed.