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": [
{
"face_id": "7032c9bb-239f-4e91-aab9-2e0fc0f857f1",
"first_name": "first_name",
"last_name": "last_name",
}
]
}
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
In the News
Turing AI to Demo Mobilized Video Security Platform, Compete in SIA New Products & Solutions Awards at ISC West
Read More >>Turing AI Introduces the Turing Partner Portal
Read More >>Turing AI Debuts Mobilized Security Platform, The First to Combine Patrol Robots and Security Camera Solutions Available on the Market
Read More >>Turing AI Launches Retail Intelligence Solution
Read More >>Turing AI Named to Inc.'s 2021 Best in Business List
Read More >>