Webhooks

Connect your tool

A webhook sends a structured alert to an address you choose whenever a new Message is created. This includes incident alerts and monitoring interruptions or recovery for all your cameras. Messages and Push continue to work as usual. Up to ten endpoints can be connected.

1. Open Settings → Webhooks and choose Add webhook.
2. Enter a name and the public HTTPS endpoint provided by your receiving service. Port 443 and a public IPv4 address are required. Local addresses and redirects are not accepted.
3. Choose Reveal secret and copy it into your receiving service. Keep it private: it verifies that a delivery came from Agentinosaurus.
4. Choose Send test, then Refresh deliveries. A Sent status means your endpoint returned a successful response. It does not confirm that your automation completed.

What arrives

Each request is a JSON POST. message.created identifies camera Messages; webhook.test identifies the test button. version is currently 1. The stable id is also sent as the webhook-id header. The example below shows an incident alert. Some fields, such as reason, are present only when relevant. incidentId is null for monitoring updates.

The data includes camera and Event names, the description, and when the event was detected. It never includes images, video, camera credentials or your OpenAI key. Only connect a service you trust with these descriptions.

{
  "id": "message_example_1",
  "type": "message.created",
  "version": 1,
  "createdAt": "2026-10-12T09:42:00.000Z",
  "data": {
    "messageId": "message_example_1",
    "cameraId": "camera_example",
    "incidentId": "incident_example",
    "cameraName": "East corridor",
    "eventName": "Blocked exit",
    "kind": "initial",
    "summary": "A trolley is blocking the exit.",
    "detectedAt": "2026-10-12T09:42:00.000Z",
    "mock": false
  }
}

Verify before acting

We use Standard Webhooks signing. Read webhook-id, webhook-timestamp and webhook-signature. Use the exact raw request body, before parsing JSON, and your endpoint’s whsec_ secret. Reject timestamps more than five minutes away from your server clock. Keep your server clock synchronized.

A Node.js receiver can use the standardwebhooks package as shown below. The verifier throws for an invalid signature or timestamp. Store the webhook ID with a unique constraint before processing, so retries cannot trigger the same action twice. Never put the secret in browser code.

import { Webhook } from 'standardwebhooks';

const rawBody = await request.text();
const headers = Object.fromEntries(request.headers);
const event = new Webhook(process.env.WEBHOOK_SECRET)
  .verify(rawBody, headers);

// Persist event and webhook-id in your durable inbox.
// An existing ID means this delivery was already accepted.
// Return 2xx after persistence, then process asynchronously.

Retries and delivery history

Return a 2xx response within ten seconds after safely saving the request. Process longer work asynchronously. Deliveries may arrive more than once or out of order. Retry attempts retain the same ID and body but get a fresh signed timestamp.

Connection failures, HTTP 408, 429 and server errors are retried automatically, up to ten total attempts, using increasing delays with jitter (about 30 seconds initially, rising to roughly six hours). Other non-success responses, including redirects, fail without automatic retries. Fix the endpoint and choose Retry delivery for a failed job.

Refresh deliveries to see the status, attempt count and response code. History is kept for thirty days. Editing the endpoint address or disabling it cancels pending deliveries. Deleting it also removes delivery history. An already in-flight request may still arrive.

Protect your secret

Endpoint URLs, signing secrets and queued alert content are encrypted in storage. Revealing a secret shows it briefly in your browser. Rotate secret immediately if you suspect exposure, then update your receiver. Newly signed attempts use the new secret; a request already in flight may still carry the previous signature.