> ## Documentation Index
> Fetch the complete documentation index at: https://docs.videodb.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Alerts and Callbacks

> Wire events to delivery channels for real-time notifications

Alerts connect events to delivery channels. Use a callback URL for server-to-server notifications, and optionally attach a WebSocket for real-time dashboards.

## Quick Example

<CodeGroup>
  ```python Python theme={null}
  # Create alert with webhook delivery
  alert_id = scene_index.create_alert(
      event_id=event_id,
      callback_url="https://your-backend.com/alerts"
  )

  # With WebSocket delivery; a callback URL is still required
  ws = conn.connect_websocket()
  await ws.connect()

  CALLBACK_URL = "https://example.com"  # Replace with a reachable endpoint you control.
  alert_id = scene_index.create_alert(
      event_id=event_id,
      callback_url=CALLBACK_URL,
      ws_connection_id=ws.connection_id
  )
  ```

  ```javascript Node.js theme={null}
  // Create alert with webhook delivery
  const webhookAlertId = await sceneIndex.createAlert(
      eventId,
      "https://your-backend.com/alerts"
  );

  // With WebSocket delivery; a callback URL is still required
  const ws = await conn.connectWebsocket();
  await ws.connect();

  const callbackUrl = "https://example.com"; // Replace with a reachable endpoint you control.
  const websocketAlertId = await sceneIndex.createAlert(
      eventId,
      callbackUrl,
      ws.connectionId
  );
  ```
</CodeGroup>

***

## Delivery Methods

| Method | Latency | Use Case |
| :- | :- | :- |
| WebSocket | Real-time | Dashboards, live UI updates |
| Webhook | Under 1s | Server-to-server, automation |

You can use both simultaneously for redundancy.

Alert creation requires a callback URL even when a WebSocket connection is attached. Replace `https://example.com` in the examples with a reachable endpoint you control.

***

## Webhook Delivery

### Create Webhook Alert

<CodeGroup>
  ```python Python theme={null}
  alert_id = scene_index.create_alert(
      event_id=event_id,
      callback_url="https://your-backend.com/webhooks/alerts"
  )
  ```

  ```javascript Node.js theme={null}
  const alertId = await sceneIndex.createAlert(
      eventId,
      "https://your-backend.com/webhooks/alerts"
  );
  ```
</CodeGroup>

### Illustrative Callback Payload

Callback payload fields can vary by pipeline and backend. Inspect and validate the payload your endpoint receives before relying on individual fields:

```json theme={null}
{
  "event_id": "event-3fd4174feceb6162",
  "label": "traffic_violation",
  "confidence": 0.95,
  "explanation": "A red sedan ran through the intersection while the light was red",
  "timestamp": "2024-01-15T10:30:45Z",
  "start_time": 1234.5,
  "end_time": 1238.0,
  "stream_url": "https://stream.videodb.io/v3/...",
  "player_url": "https://console.videodb.io/player?url=..."
}
```

### Possible Payload Fields

| Field | Type | Description |
| :- | :- | :- |
| `event_id` | string | ID of the triggered event |
| `label` | string | Human-readable event label |
| `confidence` | float | Detection confidence (0-1) |
| `explanation` | string | AI-generated description of what was detected |
| `timestamp` | string | ISO 8601 timestamp |
| `start_time` | float | Video timestamp where event starts (seconds) |
| `end_time` | float | Video timestamp where event ends (seconds) |
| `stream_url` | string | HLS stream URL for the clip |
| `player_url` | string | Web player URL |

***

## WebSocket Delivery

### Connect and Listen

<CodeGroup>
  ```python Python theme={null}
  ws = conn.connect_websocket()
  await ws.connect()

  # Pass the connection ID; a callback URL is still required
  CALLBACK_URL = "https://example.com"  # Replace with a reachable endpoint you control.
  alert_id = scene_index.create_alert(
      event_id=event_id,
      callback_url=CALLBACK_URL,
      ws_connection_id=ws.connection_id
  )

  # WebSocket messages are arbitrary decoded payloads; inspect before accessing fields.
  async for event in ws.receive():
      print(event)
  ```

  ```javascript Node.js theme={null}
  const ws = await conn.connectWebsocket();
  await ws.connect();

  // Pass the connection ID; a callback URL is still required
  const callbackUrl = "https://example.com"; // Replace with a reachable endpoint you control.
  const alertId = await sceneIndex.createAlert(
      eventId,
      callbackUrl,
      ws.connectionId
  );

  // WebSocket messages are arbitrary decoded payloads; inspect before accessing fields.
  for await (const event of ws.receive()) {
      console.log(event);
  }
  ```
</CodeGroup>

### WebSocket Channels

The current V2 alert channel is produced by the V2 scene index:

| Channel | Source | Content |
| :- | :- | :- |
| `alert` | `scene_index.create_alert()` | Alert notifications |

The following channel names are available through RTStream helper APIs:

| Channel | Source | Content |
| :- | :- | :- |
| `transcript` | `start_transcript()` | Speech-to-text |
| `scene_index` | `index_visuals()` | Visual analysis |
| `audio_index` | `index_audio()` | Audio analysis |

***

## Managing Alerts

### List Alerts

<CodeGroup>
  ```python Python theme={null}
  alerts = scene_index.list_alerts()
  for alert in alerts:
      print(f"{alert['alert_id']}: {alert['event_id']} - {alert['status']}")
  ```

  ```javascript Node.js theme={null}
  const alerts = await sceneIndex.listAlerts();
  for (const alert of alerts) {
      console.log(`${alert.alertId}: ${alert.eventId} - ${alert.status}`);
  }
  ```
</CodeGroup>

### Enable/Disable Alerts

<CodeGroup>
  ```python Python theme={null}
  # Temporarily disable
  scene_index.disable_alert(alert_id)

  # Re-enable
  scene_index.enable_alert(alert_id)
  ```

  ```javascript Node.js theme={null}
  // Temporarily disable
  await sceneIndex.disableAlert(alertId);

  // Re-enable
  await sceneIndex.enableAlert(alertId);
  ```
</CodeGroup>

## Dual Delivery Pattern

Use both channels for critical alerts:

<CodeGroup>
  ```python Python theme={null}
  # WebSocket for real-time UI
  ws = conn.connect_websocket()
  await ws.connect()

  # Create alert with both delivery methods
  alert_id = scene_index.create_alert(
      event_id=event_id,
      callback_url="https://your-backend.com/alerts",  # webhook
      ws_connection_id=ws.connection_id  # websocket
  )
  ```

  ```javascript Node.js theme={null}
  // WebSocket for real-time UI
  const ws = await conn.connectWebsocket();
  await ws.connect();

  // Create alert with both delivery methods
  const alertId = await sceneIndex.createAlert(
      eventId,
      "https://your-backend.com/alerts",  // webhook
      ws.connectionId  // websocket
  );
  ```
</CodeGroup>

**Benefits:**

* WebSocket delivers instantly to connected clients
* Webhook provides reliable server-side processing
* If WebSocket disconnects, webhook still works

***

## Latency Profile

| Event Type | Typical Latency |
| :- | :- |
| Alert trigger | Under 1s |
| Transcript event | 1-2s |
| Visual index event | 2-5s |
| Audio index event | 2-5s |

***

## Delivery Guarantees

| Method | Guarantee | Notes |
| :- | :- | :- |
| WebSocket | At-most-once | May miss events if disconnected |
| Webhook | At-least-once | May receive duplicates; use idempotency |

***

## Next Steps

<CardGroup cols={2}>
  <Card icon="webhook" title="Webhooks and Reliability" href="/pages/act/live-action/webhooks-and-reliability">
    Handle webhooks at scale with idempotency
  </Card>

  <Card icon="image" title="Event Detection Patterns" href="/pages/act/live-action/event-detection-patterns">
    Create effective detection rules
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.