Skip to main content
Alerts connect events to delivery channels. Choose WebSocket for real-time dashboards or webhooks for server-to-server notifications.

​
Quick Example

# Create alert with webhook delivery
alert_id = scene_index.create_alert(
    event_id=event_id,
    callback_url="https://your-backend.com/alerts"
)

# Or with WebSocket delivery
ws = conn.connect_websocket()
await ws.connect()

alert_id = scene_index.create_alert(
    event_id=event_id,
    ws_connection_id=ws.connection_id
)

​
Delivery Methods

MethodLatencyUse Case
WebSocketReal-timeDashboards, live UI updates
WebhookUnder 1sServer-to-server, automation
You can use both simultaneously for redundancy.

​
Webhook Delivery

​
Create Webhook Alert

alert_id = scene_index.create_alert(
    event_id=event_id,
    callback_url="https://your-backend.com/webhooks/alerts"
)

​
Webhook Payload

When an event triggers, you receive a POST request: 
{
  "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=..."
}

​
Payload Fields

FieldTypeDescription
event_idstringID of the triggered event
labelstringHuman-readable event label
confidencefloatDetection confidence (0-1)
explanationstringAI-generated description of what was detected
timestampstringISO 8601 timestamp
start_timefloatVideo timestamp where event starts (seconds)
end_timefloatVideo timestamp where event ends (seconds)
stream_urlstringHLS stream URL for the clip
player_urlstringWeb player URL

​
WebSocket Delivery

​
Connect and Listen

ws = conn.connect_websocket()
await ws.connect()

# Pass connection ID when creating alerts
alert_id = scene_index.create_alert(
    event_id=event_id,
    ws_connection_id=ws.connection_id
)

# Listen for events
async for event in ws.stream():
    if event.get("channel") == "alert":
        print(f"Alert: {event['data']['label']}")
        print(f"Confidence: {event['data']['confidence']}")

​
WebSocket Channels

ChannelSourceContent
alertEvent triggersAlert notifications
transcriptstart_transcript()Real-time speech
scene_indexindex_visuals()Visual analysis
audio_indexindex_audio()Audio analysis

​
Managing Alerts

​
List Alerts

alerts = scene_index.list_alerts()
for alert in alerts:
    print(f"{alert.id}: {alert.event_id} - {alert.status}")

​
Enable/Disable Alerts

# Temporarily disable
scene_index.disable_alert(alert_id)

# Re-enable
scene_index.enable_alert(alert_id)

​
Delete Alert

scene_index.delete_alert(alert_id)

​
Dual Delivery Pattern

Use both channels for critical alerts: 
# 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
)
Benefits:
  • WebSocket delivers instantly to connected clients
  • Webhook provides reliable server-side processing
  • If WebSocket disconnects, webhook still works

​
Latency Profile

Event TypeTypical Latency
Alert triggerUnder 1s
Transcript event1-2s
Visual index event2-5s
Audio index event2-5s

​
Delivery Guarantees

MethodGuaranteeNotes
WebSocketAt-most-onceMay miss events if disconnected
WebhookAt-least-onceMay receive duplicates; use idempotency

​
Next Steps

Webhooks and Reliability

Handle webhooks at scale with idempotency

Event Detection Patterns

Create effective detection rules