RTSP Video to JSON/Webhook Events

A video connection is only the first contract

An RTSP session gives the pipeline frames, not a business event. You still need decode readiness, timestamp handling, model observations, ROI/time rules and an event lifecycle. A successful preview should not be used as the acceptance gate for the analysis path.

Design the event envelope

Agree an event ID, schema version, source reference, event type, lifecycle phase, occurrence time and evidence reference. Use stable IDs to link updates and departure to the original event. Distinguish when an event occurred from when it was received; network interruptions can separate those times.

Treat the JSON below as an example

The illustrative payload shows one possible integration envelope, not a promise that the current product exposes these exact fields. The receiver contract, authentication and response semantics must be confirmed against the selected package. No internal network address, real camera identifier or customer plate appears in the example.

{
  "example_only": true,
  "schema": "illustrative-event-v1",
  "event_id": "sample-event-001",
  "source": "camera-example",
  "type": "zone_dwell",
  "phase": "overstay",
  "occurred_at": "2026-01-01T00:00:00Z",
  "zone": "bay-example",
  "evidence": {
    "reference": "authorized-snapshot-reference"
  },
  "plate": null
}

Retries and deduplication are acceptance work

Define request authentication, timeout, backoff, retry limits, durable buffering, receiver acknowledgments and idempotency. The current public engineering evidence does not establish a universal reliable-webhook or offline-queue guarantee. Test a timeout after the receiver has stored the event: a retry must not create a second business incident.

Evidence requires its own access policy

A snapshot reference is not permission to view an image. Decide authentication, retention, expiration and which consumer may access evidence. Prefer the least data needed for review. Do not place credentials or unrestricted evidence URLs into an analytics event or a public demo.

A receiver test matrix

Test valid events, invalid schemas, missing fields, duplicate IDs, out-of-order phases, receiver 4xx/5xx, timeouts, source restart and stream recovery. Reconcile receiver records with local evidence. Ask Hank to scope one end-to-end interface before assuming compatibility with an existing VMS, NVR or automation platform.

Handle a timeout after successful storage

One difficult receiver test is an event that was stored successfully before the response was lost. Replaying the request should update or acknowledge the same event, not create another incident. Agree whether idempotency applies to an event lifecycle or each phase update. Keep local occurrence time and receiver receipt time separate, and decide how an expired evidence reference is reported. These are interface acceptance requirements, not features that can be assumed merely from seeing a JSON payload. Include this timeout case in the receiver acceptance record.