Skip to content
NovaVMS Manual

Webhook event types

This page lists every webhook event type the NovaVMS platform currently emits. Subscribe to an event by including its name in the events array when you create or update a webhook.

Event types

Event typeSinceDescriptionSample payload
alertv1.0An alert rule matched an incoming event and fired. Includes rule, camera, event, severity, and snapshot.alert
eventv1.0A new event was recorded against a camera (motion, AI tag, manual trigger). Fires for every event, independent of alert rules.event
camera_statusv1.0A camera transitioned between online and offline. Edge-triggered — no heartbeat spam.camera_status
gateway_statusv1.0A gateway transitioned between online and offline. Includes count of affected cameras.gateway_status

These are the only event types accepted by POST /api/v1/webhooks. Supplying any other value returns 400 Validation from the API.

Event types that sound plausible (event.created, alert.fired, clip.exported, user.invited, user.activated) are not emitted by v1.x. Future event types will be added here with the version in which they first ship.

Sample payloads

Every delivery is wrapped in the same envelope:

{
  "event_type": "<event-type>",
  "timestamp": "2026-04-21T14:30:00Z",
  "webhook_id": "7e4c2a91-8b3f-4d6a-9c1e-2f5a8b3c4d7e",
  "data": { }
}

timestamp is RFC 3339 UTC. webhook_id is the UUID of the delivery attempt and matches the X-Webhook-ID header. The per-event data shapes follow.

alert

{
  "event_type": "alert",
  "timestamp": "2026-04-21T14:30:00Z",
  "webhook_id": "7e4c2a91-8b3f-4d6a-9c1e-2f5a8b3c4d7e",
  "data": {
    "alert_id": "b1c9d3e5-4a6f-4812-a7bc-0d9e8f7a6b5c",
    "rule_id": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
    "rule_name": "Entrance person after hours",
    "trigger_type": "ai_tag",
    "camera_id": "8f2b3a71-0c4e-4b5f-9d1a-2e7c3a4b5d6f",
    "camera_name": "Lobby Camera",
    "site_name": "Headquarters",
    "event_id": "3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f",
    "severity": "warning",
    "description": "Person detected at main entrance",
    "tags": ["person", "entrance", "walking"],
    "snapshot_url": "https://media.novavms.io/snap/3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f.jpg",
    "event_url": "https://app.novavms.io/events/3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f",
    "is_test": false
  }
}

event

{
  "event_type": "event",
  "timestamp": "2026-04-21T14:30:00Z",
  "webhook_id": "2d1e9c8b-7a6f-5e4d-3c2b-1a0f9e8d7c6b",
  "data": {
    "event_id": "3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f",
    "camera_id": "8f2b3a71-0c4e-4b5f-9d1a-2e7c3a4b5d6f",
    "camera_name": "Lobby Camera",
    "site_name": "Headquarters",
    "trigger_type": "onvif_motion",
    "triggered_at": "2026-04-21T14:29:58Z",
    "description": "Person detected at entrance",
    "tags": ["person", "entrance"],
    "ai_severity": "info",
    "snapshot_url": "https://media.novavms.io/snap/3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f.jpg"
  }
}

camera_status

{
  "event_type": "camera_status",
  "timestamp": "2026-04-21T14:30:00Z",
  "webhook_id": "5f6a7b8c-9d0e-1f2a-3b4c-5d6e7f8a9b0c",
  "data": {
    "camera_id": "8f2b3a71-0c4e-4b5f-9d1a-2e7c3a4b5d6f",
    "camera_name": "Lobby Camera",
    "site_name": "Headquarters",
    "status": "offline",
    "previous_status": "online",
    "offline_since": "2026-04-21T14:25:00Z"
  }
}

gateway_status

{
  "event_type": "gateway_status",
  "timestamp": "2026-04-21T14:30:00Z",
  "webhook_id": "0a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
  "data": {
    "gateway_id": "4d5e6f7a-8b9c-0d1e-2f3a-4b5c6d7e8f90",
    "gateway_name": "Site A Gateway",
    "site_name": "Headquarters",
    "status": "offline",
    "previous_status": "online",
    "cameras_affected": 12
  }
}

Signature header

Every delivery carries an HMAC-SHA256 signature in the X-Webhook-Signature header, computed over the raw request body with the webhook’s secret. See Verify a webhook signature for code samples in TypeScript, Python, and Go.

Delivery semantics

  • At-least-once. A single event may arrive more than once after transient network failures. Deduplicate on X-Webhook-ID or on the alert_id / event_id / camera_id / gateway_id inside data.
  • Retry policy. On any response outside 2xx, NovaVMS retries up to 5 times with exponential backoff (1 s, 5 s, 30 s, then longer).
  • Timeout. Each delivery attempt waits 15 s for a response before it counts as a failure.
  • Auto-disable. After 5 consecutive failed deliveries the webhook is disabled; admins receive an in-app notification. See Webhook delivery failures.
  • Ordering. Deliveries are not strictly ordered. Use the envelope timestamp to reorder on the receiver.