Ayonix Video Analytics

Developers

Event webhooks: building a receiver that holds up

In short

This page describes how to build a webhook receiver for analytics events — signature verification before parsing, idempotent handling, fast acknowledgement with asynchronous processing, and bounded retries with a dead-letter path. The concrete payload contract is supplied by Ayonix under evaluation access.

Scope

What is on this page, and what needs access

Published here

  • Receiver design principles that apply to any webhook integration
  • Security controls a receiver must implement
  • Delivery semantics and what they mean for your handler
  • Operational requirements — monitoring, dead-lettering and replay

Requires evaluation access

  • The event payload schema and event type taxonomy
  • The request signing scheme and header names
  • Retry policy and timeout values
  • Event identifier format and semantics

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.

Verify before you parse

The single most important rule for a webhook receiver: verify the request signature before your code parses the body. Parsing unauthenticated input exposes your parser to anyone who can reach the endpoint.

  • Read the raw body, verify the signature against it, and only then parse
  • Use a constant-time comparison for signature verification
  • Reject requests whose timestamp is outside a narrow tolerance window, to limit replay
  • Return a clear rejection without revealing why verification failed
  • Never fall back to accepting unsigned requests, not even temporarily during setup

Assume at-least-once delivery

Any retry-capable delivery system will occasionally deliver the same event twice. A receiver that is not idempotent will create duplicate alerts, duplicate tickets and duplicate work.

  • Key handling on the stable event identifier supplied in the payload
  • Record processed identifiers for long enough to cover the retry window
  • Make the side effect itself idempotent where possible, rather than only the handler
  • Treat a duplicate as a normal occurrence, not an error condition to alert on

Acknowledge fast, process asynchronously

A receiver that does its work before responding will time out under load, trigger retries and create the very backlog it was trying to avoid.

  • Validate, enqueue and acknowledge within the timeout — do the work afterwards
  • Size the queue and its consumers for peak event volume, not average
  • Apply backpressure within your own system rather than by responding slowly
  • Monitor queue depth as a leading indicator of trouble

Failure handling and replay

Events you cannot process must go somewhere you will actually look, or they become silent data loss.

  • Route permanently failed deliveries to a dead-letter store with the full payload and failure reason
  • Alert on dead-letter volume rather than on individual failures
  • Build a replay path so a fixed handler can reprocess dead-lettered events
  • Retain enough context to diagnose a failure without asking for the event to be resent

Security controls

A webhook endpoint is a publicly reachable surface that accepts unauthenticated traffic until you prove otherwise. Treat it with the same care as any other public API, because that is exactly what it is.

  • HTTPS only, with a valid certificate and no plaintext fallback
  • Enforce a maximum payload size and reject anything larger before buffering it
  • Rate-limit the endpoint independently of your application limits
  • Log a request identifier per delivery, with no media and no personal data in the log
  • Keep the endpoint path non-guessable, as defence in depth rather than as the control itself

Frequently asked questions

What does the payload look like?

The schema is supplied by Ayonix under evaluation access. This page deliberately publishes no payload structure, because building against an invented schema wastes engineering effort and produces a receiver that will not work.

Should we verify signatures in production only?

No — verify everywhere, including development and staging. Environments where verification is disabled become the ones that get exposed, and a fallback that accepts unsigned requests almost always outlives the setup period it was added for.

How long should we keep processed event identifiers?

At least as long as the retry window, plus a margin. Agree the retry policy with Ayonix during integration scoping so the retention period is based on the actual policy rather than a guess.

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 webhook integration details Read the architecture guidance