Header

Every notification carries a TL-Signature header. Use it to verify that the notification came from TwelveLabs. The header value has two parts:

• t: A Unix timestamp for the moment the platform sent the notification.
• v1: A signature generated for this notification with HMAC-SHA256. For the verification steps, see Validate the integrity of a notification.

Envelope

Every notification is JSON with the same top-level shape:

• id: The unique identifier of the notification. Starts with the whe_ prefix.
• created_at: The date and time, in RFC 3339 format, when the platform sent the notification.
• type: The event type. Use this field to route the notification. Supported values: index.task.ready, index.task.failed, analyze.task.ready, analyze.task.failed, analyze.task.canceled.
• data: An object whose shape depends on the type value. See the per-event sections below.

Video indexing events

The platform sends these notifications for video indexing tasks.

index.task.ready

The platform sends this notification when a video indexing task reaches the final ready status.

data fields:

• id: The unique identifier of the video indexing task.
• metadata: An object with video metadata, such as the video duration field.
• status: The final status of the task. Always ready for this event.
• models: The video understanding models and the associated model options used to index the video.
• tags: The tags associated with the task.

Example:

POST /user-webhook-endpoint HTTP/1.1
TL-Signature: t=1659342128,v1=0f596565898448fe00d22c52fcaddffb1d1054da3b1d47268b99b6041c79aa29
{
  "id": "whe_7b86d081884c4d659a2feaa0c55ad013",
  "created_at": "2026-09-14T10:29:30.123Z",
  "type": "index.task.ready",
  "data": {
    "id": "64f8d2c7e4a1b37f8a9c5d12",
    "metadata": { "duration": 30 },
    "status": "ready",
    "models": [
      { "name": "marengo3.0", "options": ["visual", "audio"] }
    ],
    "tags": []
  }
}

index.task.failed

The platform sends this notification when a video indexing task reaches the final failed status.

data fields: The same shape as the index.task.ready event, with the status field set to the failed value.

Asynchronous analysis events

The platform sends these notifications for asynchronous analysis tasks. Tasks created as part of a batch do not produce these per-task notifications.

Every analyze event data object contains:

• id: The unique identifier of the analysis task.
• custom_id: The value provided in the custom_id field at task creation, or null if it was not set. The key is always present.
• status: The final status of the task. Matches the event type.
• created_at: The date and time, in RFC 3339 format, when the analysis task was created.
• video_source: The video source associated with the task. Omitted when video-source information is unavailable.

analyze.task.ready

The platform sends this notification when an asynchronous analysis task reaches the final ready status.

For general analysis, generation can stop at the output-token limit or the model context window and leave a partial result while status is still ready. In that case, data.error.message describes why the output was truncated. Retrieve the task to inspect the result.

Additional data field:

• error: An object whose message describes why a ready task has a partial result. Omitted when the task has a complete result.

Example:

POST /user-webhook-endpoint HTTP/1.1
TL-Signature: t=1659342128,v1=0f596565898448fe00d22c52fcaddffb1d1054da3b1d47268b99b6041c79aa29
{
  "id": "whe_7b86d081884c4d659a2feaa0c55ad013",
  "created_at": "2026-09-14T10:29:30.123Z",
  "type": "analyze.task.ready",
  "data": {
    "id": "64f8d2c7e4a1b37f8a9c5d12",
    "custom_id": "prod-segment-analysis-42",
    "status": "ready",
    "created_at": "2026-09-14T10:29:19.968Z",
    "video_source": {
      "type": "asset_id",
      "asset_id": "64f8d2c7e4a1b37f8a9c5d11",
      "system_metadata": { "duration": 120.5 }
    }
  }
}

analyze.task.failed

The platform sends this notification when an asynchronous analysis task reaches the final failed status.

Additional data field:

• error: An object whose message describes the failure. Omitted when no failure reason is available.

Example:

POST /user-webhook-endpoint HTTP/1.1
TL-Signature: t=1659342128,v1=0f596565898448fe00d22c52fcaddffb1d1054da3b1d47268b99b6041c79aa29
{
  "id": "whe_8c86d081884c4d659a2feaa0c55ad014",
  "created_at": "2026-09-14T10:29:30.123Z",
  "type": "analyze.task.failed",
  "data": {
    "id": "64f8d2c7e4a1b37f8a9c5d12",
    "custom_id": null,
    "status": "failed",
    "created_at": "2026-09-14T10:29:19.968Z",
    "video_source": {
      "type": "url",
      "url": "https://example.com/video.mp4",
      "system_metadata": { "duration": 120.5 }
    },
    "error": {
      "message": "Video duration exceeds maximum allowed duration"
    }
  }
}

analyze.task.canceled

The platform sends this notification after an asynchronous analysis task reaches the final canceled status through the cancellation endpoint. Canceling an already canceled task does not produce another notification.

The notification does not include the cancellation reason. Retrieve the task to read it.

Example:

POST /user-webhook-endpoint HTTP/1.1
TL-Signature: t=1659342128,v1=0f596565898448fe00d22c52fcaddffb1d1054da3b1d47268b99b6041c79aa29
{
  "id": "whe_9f86d081884c4d659a2feaa0c55ad015",
  "created_at": "2026-09-14T10:29:30.123Z",
  "type": "analyze.task.canceled",
  "data": {
    "id": "64f8d2c7e4a1b37f8a9c5d12",
    "custom_id": "prod-segment-analysis-42",
    "status": "canceled",
    "created_at": "2026-09-14T10:29:19.968Z",
    "video_source": {
      "type": "asset_id",
      "asset_id": "64f8d2c7e4a1b37f8a9c5d11",
      "system_metadata": { "duration": 120.5 }
    }
  }
}

Delivery

Delivery is best-effort. Deduplicate on the id field. For the retry policy, failure handling, and how to inspect delivery state, see Respond with a 2xx status code.