Developer Docs

Webhook Documentation

Subscribe to real-time AI event data from Turing cameras. Receive POST requests to your endpoint whenever a subscribed event is triggered.

Real-time Events

HMAC Signature Auth

JSON Payloads

REST / POST

Overview

Webhooks allow you to subscribe to all event data generated by Turing AI. Once configured, all AI results detected from camera events will be automatically pushed via HTTP POST to your defined endpoint URL in real time.

Real-Time Push

Events delivered instantly as they are detected by the AI engine.

Signature Verification

Every request is signed with HMAC-MD5 so you can verify its authenticity.

Structured JSON

All payloads follow a consistent, versioned JSON schema.

Preparation

To receive event data, you need to build a custom endpoint that can receive concurrent POST requests. Turing will send a POST request to your endpoint with the event data in JSON format once your subscribed event is triggered.

Response Requirements

Your endpoint must respond with HTTP 200 upon receipt.
If a 429 or 5xx status is returned, delivery will be retried 3 times.
If your endpoint does not respond within 5 seconds, the delivery is considered failed with no further retries.

Event Subscription Options

You can subscribe to receive notifications for two event types: people and vehicle. For each type, you may choose to receive notifications at one of two trigger stages:

Stage 1

After Creation

The payload will include basic event information — the Base Event payload. No AI analysis results are included at this stage.

Stage 2

After Processed

The payload is enriched with AI analysis: Facial Recognition (FR) for people events, and License Plate Recognition (LPR) for vehicle events.

Event Type	Stage	AI Enrichment
`people`	`created`	None (Base payload)
`people`	`processed`	Facial Recognition (FR)
`vehicle`	`created`	None (Base payload)
`vehicle`	`processed`	License Plate Recognition (LPR)

Base Event Payload

When subscribing to notifications at the creation stage for either people or vehicle events, you will receive the Base Event payload. It includes the following fields:

Parameter	Type	Required	Description
`event_id`	string	Yes	Unique identifier for the event.
`event_type`	string	Yes	Either `people` or `vehicle`.
`timestamp`	string	Yes	ISO 8601 UTC timestamp of when the event occurred.
`camera`	object	Yes	Object with camera `id` (integer) and `name` (string).
`site`	object	Yes	Object with site `id` (integer) and `name` (string).
`mediums`	array	Yes	Array of media objects containing snapshot file URLs.

JSON

{
  "event_id": "65d3a17da3ab8d796a37fec1",
  "event_type": "vehicle",
  "timestamp": "2024-02-19T18: 44:12Z",
  "camera": {
    "id": 10577,
    "name": "IP Camera 06"
  },
  "site": {
    "id": 11120,
    "name": "Demo Site 1"
  },
  "mediums": [
    {
      "files": [
        { "url": "<snapshot-url>" }
      ],
      "name": "snapshot"
    }
  ]
}

People Event — After Processing

Upon processing, the people event payload is enriched with snapshots, video clips, and metadata including detected individuals' appearance attributes and Facial Recognition (FR) results.

Additional fields in the metadata array:

Parameter	Type	Required	Description
`attributes`	array	No	Array of appearance attributes: `hat` (boolean), `upper_color`, `lower_color`, `upper_wear`, `lower_wear`.
`people`	array	No	Matched face records. Each entry has `face_id`, `first_name`, `last_name`, and `medium` (face image URL).

JSON

{
  "event_id": "65c168a5f46480c13e580ed5",
  "event_type": "people",
  "timestamp": "2024-02-05T23: 00:22Z",
  "camera": {
    "id": 141878,
    "name": "IP Camera 05"
  },
  "site": {
    "id": 1789,
    "name": "Demo Site 1"
  },
  "mediums": [
    {
      "files": [{ "url": "<snapshot-url>" }],
      "name": "snapshot"
    },
    {
      "files": [{ "url": "<video-clip-url>" }],
      "name": "video"
    }
  ],
  "metadata": [
    {
      "attributes": [
        {
          "hat": false,
          "lower_color": [
            { "confidence": 0.8875, "value": "black" }
          ],
          "lower_wear": "long",
          "upper_color": [
            { "confidence": 0.5775, "value": "black" },
            { "confidence": 0.5178, "value": "blue" }
          ],
          "upper_wear": "long"
        }
      ],
      "people": [
        {
          "face_id": "b46d34d5-8fee-46b9-86ea-6dc9b84449b4",
          "first_name": "Test",
          "last_name": "Name",
          "medium": "https://example.com/face.jpg"
        }
      ]
    }
  ]
}

Vehicle Event — After Processing

The vehicle event payload after processing includes the snapshot and metadata such as the vehicle's color, make, model, and license plate text.

Parameter	Type	Required	Description
`color`	string	No	Detected vehicle color (e.g. "black", "white").
`license_plate_text`	string	No	Recognized license plate number. Empty string if not detected.
`make`	string	No	Vehicle manufacturer (e.g. "Honda"). Empty if not detected.
`model`	string	No	Vehicle model (e.g. "Civic"). Empty if not detected.

Note: If your organization is configured for image-based License Plate Recognition (LPR), video clips may not be included in vehicle event payloads.

JSON

{
  "event_id": "65d3a17da3ab8d796a37fec1",
  "event_type": "vehicle",
  "timestamp": "2024-02-19T18: 44:12Z",
  "camera": {
    "id": 10577,
    "name": "IP Camera 06"
  },
  "site": {
    "id": 11120,
    "name": "Demo Site 1"
  },
  "mediums": [
    {
      "files": [{ "url": "<snapshot-url>" }],
      "name": "snapshot"
    }
  ],
  "metadata": [
    {
      "color": "black",
      "license_plate_text": "ABC1234",
      "make": "Honda",
      "model": "Civic"
    }
  ]
}

Authentication

For security, Turing AI signs every webhook request using HMAC-MD5. You should always verify the signature before processing any event.

Parameter	Type	Required	Description
`x-turingvideo-signature`	string	Yes	HMAC-MD5 hex digest of the raw request body, signed with your configured secret key.
`Content-Type`	string	Yes	Always `application/json`.

Extract the signature header

Read the x-turingvideo-signature header from the incoming request.

Compute the expected signature

Use HMAC with the MD5 digest function. Your configured secret is the key; the raw request body is the message.

Compare both signatures

If the signatures match, the request is authentic. If they differ, reject it immediately.

Python

import hmac
import hashlib

# 1. Extract the signature from the request header
signature = request.headers.get("x-turingvideo-signature")

# 2. Generate the expected signature
#    Compute HMAC with MD5. Use your configured secret as key,
#    and the raw request body as the message.
expected_signature = hmac.new(
    secret_key.encode(),
    msg=request.get_data(),
    digestmod=hashlib.md5
).hexdigest()

# 3. Compare signatures
if signature != expected_signature:
    raise ValueError("Signature verification failed")

Contact & Testing

To initiate testing for event integration via webhook, submit the following details to support@turingvideo.com:

Required

Event type — people or vehicle
Trigger stage — created or processed
Endpoint URL — Your server URL to receive events

Optional

Custom headers — Any headers to include in requests
Secret key — For HMAC signature verification