> 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.

# Notification schema

> Reference for webhook notifications. Header, envelope, and per-event data schemas.

# 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](/v1.3/docs/advanced/webhooks/requirements-for-processing-notifications#1-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](/v1.3/docs/concepts/models) and the associated [model options](/v1.3/docs/concepts/modalities#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](/v1.3/api-reference/analyze-videos/cancel-an-async-analysis-task). 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](/v1.3/docs/advanced/webhooks/requirements-for-processing-notifications#2-respond-with-a-2xx-status-code).