Header

The header contains a field named TL-Signature. This allows you to verify that the event was sent by TwelveLabs. The TL-Signature field is composed of two parts:

• t: A Unix timestamp representing the time when the platform sent the notification.
• v1: A signature generated uniquely for each webhook event, using HMAC with SHA-256. For instructions on how to verify the signature, see the Validate the integrity of an event section.

Response schema

All notifications are in JSON format and contain the following top-level fields:

• id: A string representing the unique identifier of the notification.
• created_at: A string indicating the date and time, in RFC 3339 format, when the platform sent the notification.
• type: A string indicating the event type. Use this field to determine whether the notification is for a video indexing task or an async analysis task.
• data: An object containing event-specific fields. The fields depend on the event type. See the sections below for details.

Video indexing notifications

These notifications apply to video indexing tasks. The type field is index.task.ready or index.task.failed.

The data object contains the following fields:

• id: A string representing the unique identifier of the video indexing task.
• metadata: An object containing metadata about the video, such as its duration.
• status: A string representing the status of the video indexing task. For details about the possible statuses, see the Task object page.
• models: A list of objects containing the video understanding models and the associated model options used to index this video.
• tags: An array of strings representing the tags associated with this video indexing task.

Example

POST /user-webhook-endpoint HTTP/1.1
TL-Signature: t=1659342128,v1=0f596565898448fe00d22c52fcaddffb1d1054da3b1d47268b99b6041c79aa29
{
  "id": "whe_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "created_at": "2022-08-01T17:22:18.372553+09:00",
  "type": "index.task.ready",
  "data": {
    "id": "xxxxxxxxxxxxxxxxxxxxxxx",
    "metadata": { "duration": 30 },
    "status": "ready",
    "models": [
      {
        "name": "marengo3.0", "options": ["visual", "audio"]
      },
      {
        "name": "pegasus1.2", "options": ["visual", "audio"]
      }
    ],
    "tags": []
  }
}

Async analysis notifications

These notifications apply to async analysis tasks. The type field is analyze.task.ready or analyze.task.failed.

The data object contains the following fields:

• id: A string representing the unique identifier of the analysis task.
• status: A string representing the status of the analysis task. It is either ready or failed.
• created_at: A string indicating the date and time, in RFC 3339 format, when the analysis task was created.
• error: An object containing a message field that describes the failure. The platform includes this field only when status is failed.

Example

POST /user-webhook-endpoint HTTP/1.1
TL-Signature: t=1659342128,v1=0f596565898448fe00d22c52fcaddffb1d1054da3b1d47268b99b6041c79aa29
{
  "id": "whe_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "created_at": "2024-09-26T10:30:45.123Z",
  "type": "analyze.task.ready",
  "data": {
    "id": "64f8d2c7e4a1b37f8a9c5d12",
    "status": "ready",
    "created_at": "2024-09-26T10:29:19.968Z",
    "error": { "message": "..." }  // only on failure
  }
}