Webhook Documentation

Webhook allows you to subscribe all event data generated by Turing AI. Once the webhook notification is configured to be received, all AI results detected from camera event will be automatically pushed to the defined URL.

Preparation

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

Upon receipt of the event data, your endpoint is required to respond with a 200 HTTP status code. If a 429 or 500-range HTTP status code is received, the webhook notification will attempt to retry three times. If your endpoint fails to provide a response within 5 seconds, the webhook notification will be considered as a failure, and no further retries will be initiated.

Event Subscription Options

You can subscribe to receive notifications for two types of events: people and vehicle. You have the option to receive notifications at two different stages for each event type: when the event is created and after the event has been processed.

Event Subscription Stage Options

Event After Creation

When you subscribe to receive notifications after the event creation stage, the payload will include basic event information, known as the Base Event payload.

Event After Processed

If you choose to receive notifications after the event has been processed, the payload will be enriched with AI-generated analysis results. For the people event, this includes data from Facial Recognition (FR) showing detected faces. For the vehicle event, it includes data from License Plate Recognition (LPR) showing detected vehicles.

Event Payload

The event payload is a JSON object that contains the event data. The payload structure is different depending on the event type and stage.

Base Event Payload

When subscribing to notifications for the creation of either people or vehicle events, you will receive a Base Event payload that includes the following information:

Event ID
Event Type: people or vehicle
Timestamp
Camera Information: ID and Name
Site Information: ID and Name
Mediums: event's snapshots urls

Base Event Payload Example:

{
    "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"
        }
    ]
}

Processed Event Payload

1. People Event (After Processing)

Upon processing, the people event payload includes event's snapshot, video clip and metadata such as detected individuals' names.

{
    "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.887520489692638,
              "value": "black"
            },
          ],,
          "lower_wear": "long",
          "upper_color": [
            {
              "confidence": 0.577520489692688,
              "value": "black"
            },
            {
              "confidence": 0.5178483724594116,
              "value": "blue"
            }
          ],
          "upper_wear": "long"
        }
      ],
      "people": [
        {
          "face_id": "b46d34d5-8fee-46b9-86ea-6dc9b84449b4",
          "first_name": "Test",
          "last_name": "Name",
          "medium": "https://xxxxxxx.xxx"
        }
      ]
    }
]
}

2. Vehicle Event (After Processing)

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

{
    "event_id": "65d3a17da3ab8d796a37fec1",
    "event_type": "vehicle",
    "timestamp": "2024-02-19T18:44:12Z",
    "camera": {
        "id": 10577,
        "name": "IP Camera 06"
    },
    "site": {
        "id": 11120,
        "name": "test@turingvideo.com"
    },
    "mediums": [
        {
        "files": [
            {
                "url":  <snapshot-url>
            }
        ],
        "name": "snapshot"
        },
    ],
    "metadata": [
        {
            "color": "black",
            "license_plate_text": "",
            "make": "",
            "model": "civic"
        }
    ]
}

Note: If your organization is configured for License Plate Recognition (LPR) based on images, you might not receive the video clips for vehicle events.

Authentication

For security reasons, Turing AI incorporates a signature mechanism for your to verify the event data were sent by Turing AI.

1. Extract the signature from the request header.

signature = request.Header.Get("x-turingvideo-signature")

2. Generate the expected signature

Compute HMAC with MD5 hash function. Use the secret you configured for receiving webhook as the key and the received message payload as the message.

3. Compare two signatures.

The last step is to compare the signature you received from Turing AI(as outlined in step1) and the signature you derived in step 2.

Pseudo Python code as below:

                            
    import hmac
    import hashlib
    
    // Extract the signature from the request header
    signature = request.Header.Get("x-turingvideo-signature")

    // Generate the expected signature. 
    // Compute HMAC with MD5 hash function. Use the secret you configured for receiving webhook as the key and the received message payload as the message. 
    expectedSignature = hmac.new(
        secret_key.encode(),
        msg=request.get_data()
        digestmod=md5
    ).hexdigest()

    // Compare two signatures
    if signature != expectedSignature {
    // Signature verification failed
        raise Error
    }

Contact

If you wish to initiate testing for event integration via webhook, kindly submit the following details to support@turingvideo.com

Required details:

Event type and trigger stage
- Event type: people or vehicle
- Trigger stage: created or processed
Endpoint: URL to receive the event data

Optional details:

Headers: Custom headers
Secret: A secret key for signature verification