Ayonix Video Analytics

Developers

Integration architecture: choosing the right route

In short

Four integration routes exist — VMS plugin, webhook delivery, data retrieval and SDK embedding — and the right one follows from who consumes the output and where processing runs. Choosing the wrong route is the commonest cause of integration projects that take twice as long as planned.

Scope

What is on this page, and what needs access

Published here

  • How to choose between the four integration routes
  • How the deployment model constrains integration options
  • The architectural decisions that should be made before any code is written
  • Health, observability and failure-handling requirements common to all routes

Requires evaluation access

  • Concrete interface contracts for each route
  • Supported versions and platform requirements
  • Licensing model per integration route
  • Performance characteristics for your specific configuration

No endpoint path, class name, method signature or response shape appears anywhere on these pages. Ayonix does not publish a public interface specification, and documenting an invented one would waste your engineering time building against a contract that does not exist.

Start from the consumer, not the interface

The route follows from who acts on the output. Teams that start by choosing an interface and then look for a consumer usually end up building a bridge nobody needed.

  • A security operator in an existing VMS → VMS integration, so they stay in one console
  • An operational system reacting to events as they happen → webhook delivery
  • A BI or reporting tool consuming series and history → data retrieval
  • A product you build that embeds analytics as a component → SDK
  • More than one consumer is normal; routes combine rather than compete

The deployment model constrains the options

Where processing runs determines what integration is available. This is the constraint most often discovered too late.

  • Air-gapped deployments cannot use any integration that requires outbound connectivity
  • Edge deployments should deliver locally for anything latency-sensitive, and forward aggregates centrally
  • Hybrid deployments split naturally: local delivery for alerts, central retrieval for reporting
  • On-premise deployments have the widest option set because everything is inside one network
  • Confirm the deployment model before designing the integration, not afterwards

Decisions to make before writing code

Integration projects rarely fail on the code. They fail on decisions that were never explicitly made.

  • Which events matter, and which are noise that should never leave the analytics layer
  • What happens to events when the consumer is unavailable — buffer, drop or dead-letter
  • Who owns the camera-to-entity mapping and keeps it current as cameras change
  • How clock synchronisation is assured, since event timestamps drive video navigation
  • What the failure alert looks like, and who receives it
  • How the integration is tested before it carries production events

Observability across the whole path

The hardest integration failures are the quiet ones: events stop arriving and nobody notices for a week because nothing errored.

  • Monitor event volume as well as errors — a sudden drop to zero is the signal that matters
  • Surface camera stream availability alongside event counts, so a quiet camera is distinguishable from a broken one
  • Propagate a request or event identifier end to end so a single event can be traced across systems
  • Alert on the absence of expected events, not only on failures
  • Keep media out of logs entirely, and redact personal data before anything is written

Frequently asked questions

Can we use more than one integration route?

Yes, and most mature deployments do. Security events go to the VMS, operational events go to a webhook consumer, and reporting pulls series through retrieval. The routes serve different consumers rather than competing.

What is the commonest integration mistake?

Choosing the route before identifying the consumer, closely followed by not deciding what happens when the consumer is unavailable. Both are decisions rather than code, and both are cheap to make early and expensive to retrofit.

Why does clock synchronisation keep coming up?

Because event timestamps drive video navigation. If analytics and VMS clocks differ by thirty seconds, every operator who clicks an event lands at the wrong moment in the recording and concludes the analytics is wrong.

Other developer pages

Author
Gabriel Bamola, Chief Marketing Officer, Ayonix
Technical review
Dr Sadi Vural, Founder and Chief Executive Officer, Ayonix
Published
Last reviewed

Request evaluation access

Evaluation access includes the interface documentation, licensing details and supported-platform information that this site deliberately does not publish. Tell us what you are building and an engineer will scope it with you.

Request an architecture review Read the architecture guidance