Protect WebHook

Revisions Summary

Introduction

Protect Webhooks provide a powerful and flexible way to receive real-time notifications when alerts are triggered within the Protect system. By leveraging webhooks, users can automate responses, enhance situational awareness, and streamline their security operations.

The payload structure and content enable seamless integration with various third-party applications and services.

Webhook Payload Format

The webhook sends a JSON payload via HTTP POST with the application/json content type. The payload contains two main fields: a human-readable summary (text) and a structured data object (alertData).

This message design is compatible with Slack-style receivers while providing detailed structured data for robust integrations.

JSON Structure

JSON

{
  "text": "New Alert! ...",
  "alertData": {
    /* Structured Alert Details */
  }
}

Payload Content

1. text Field (Human-Readable Summary)

The text field is a human-readable message summarizing the alert. It includes key alert details, such as:

• Created: Timestamp of alert creation.

• Rule Name: Name of the rule that triggered the alert.

• Stream Name: Camera or stream where the alert occurred.

• Priority: Priority level of the alert (e.g., High, Medium, Low).

• Person Name: Matched entity name (if any).

• Crop: URL to cropped image of detected person (Expires within 1 hour).

• Alert Video: URL to watch the full alert video (Expires within 1 hour).
  

2. alertData Field (Structured Data)

The alertData object contains the complete, structured details of the event.

Example Payload (Updated Format)

JSON

{
  "text": "\nNew Alert! \nCreated: 15:55:30 Wed, 26 Nov 2025 UTC\nRule Name: Sample Rule\nStream Name: Entrance Camera\nPriority: Medium\nPerson Name: Unknown\nCrop: https://media.example.com/l/image-crop-ABC.jpg\n\nAlert Video: https://media.example.com/l/video-alert-XYZ",
  "alertData": {
    "eventId": "1234abcd-f596-4d09-a4eb-f42e4881c566",
    "ruleId": "9876efgh-0da7-4c75-8df0-3f7495261c54",
    "ruleName": "Sample Rule",
    "priority": "Medium",
    "authorizationType": "None",
    "trackId": "5555bbbb-19ab-48df-b7f6-57f8c1309522",
    "matchedString": "All",
    "creationTimestamp": "2025-11-26T15:55:30.987998088Z",
    "alertType": "Face",
    "action": "",
    "entity": null,
    "stream": {
      "streamId": "1111aaaa-0ff7-41e1-8d53-f350ee57d03f",
      "streamName": "Entrance Camera"
    },
    "media": {
      "videoUrl": "https://media.example.com/l/video-alert-XYZ",
      "imageUrl": "https://media.example.com/l/image-crop-ABC.jpg"
    }
  }
}

Webhook Configuration Options

The Protect system offers methods to enhance security and extend the data payload beyond the default fields.

Injecting Parameters via URL

You can add custom parameters or authentication credentials to the webhook's JSON body by including them in the URL query string and applying a specific suffix.

Rules for Injectable Parameters

1. To mark a parameter for injection into the JSON body, add the suffix -~ after its name (e.g., systemId-~).

2. Parameters with the -~ suffix are moved from the URL into the JSON body of the request (the suffix is removed in the JSON key).

3. Parameters without the -~ suffix remain in the URL.

4. Authentication Header: Use the parameter name Authheader-~ to inject a header value.

• The value of this parameter must be the Base64 encoded credential string (e.g., username:password or API_KEY).

• The system will automatically add the resulting value to the standard Authorization HTTP header of the message. This allows the standard Authorization parameter name to still be used in the URL if needed.

Examples

Special Notes

• The webhook is sent to each configured webhook URL in the system.

• If a webhook delivery fails for any reason (e.g., network error, permission issue, invalid URL), the system automatically retries all failed webhook deliveries every 10 minutes until successful.

• Media URLs (Crop and Alert Video) expire within 1 hour of the alert creation.