Alert Webhooks

Overview

The Genlogs webhooks integration sends notifications when alerts are triggered and matches are found in truck detections. The system operates with a clear separation between webhook endpoints and alert configurations:

• Webhooks: Define where notifications are sent (URL and authentication)

• Alerts: Define what to search for (license plates, VINs, USDOT numbers, etc.)

Only enabled webhooks (enabled = true) will receive notifications during processing.

How Webhook Alerts Work

Webhook alerts operate using the same processing system as email alerts:

• Unified Processing: Both webhook and email alerts use identical search algorithms and scheduling

• Same Data Source: Webhooks receive the exact same detection matches that would trigger email notifications

• Parallel Delivery: When alerts find matches, the system simultaneously:

  • Sends email notifications to the configured email addresses

  • Sends webhook payloads to all active webhook endpoints

• Consistent Timing: Webhook notifications are sent at the same time as email alerts during each processing cycle

• Shared Alert Rules: The same alert configurations trigger both email and webhook notifications

Current Trigger Methods:

1. Manually from the Asset Locator UI using the “Run Alert Summary” button.

2. Programmatically by calling the /run endpoint from the API.

3. Automatically once per day in the morning via a scheduled background process.

This means if you currently receive email alerts, enabling webhooks will provide you with the same alert data via HTTP requests to your chosen endpoints.

Key Features

• Separate Management: Webhooks and alerts are managed independently

• Consolidated Notifications: Receive one payload with all matches from all your alerts

• Secure & Reliable: Uses HMAC-SHA512 signature verification and HTTPS-only endpoints

• Pre-flight Testing: Test your webhook endpoint before deploying

• Cron-Driven Processing: Alerts are processed on a schedule to find new matches since the last run

Security

• HMAC-SHA512 Signatures: All payloads are signed for authenticity verification

• Unique Secret Keys: Each webhook has its own secret key

• HTTPS-only URLs: Required for all webhook endpoints in production

• JWT Authentication: API access protected by JWT tokens

• Role-Based Access Control: Requires specific user roles to manage webhooks

Webhook Payload Format

When one or more alerts find new matches, GenLogs sends a payload with the event type alert.matches_found.

Payload Structure

Imputed Fields

Fields is_usdot_imputed, is_cab_imputed, is_mc_imputed, is_trailer_logo_imputed and is_vin_imputed represent whether the corresponding field value was inferred or auto-filled by the system rather than directly observed.

These fields are boolean and help differentiate between raw observations and system-generated estimations.

*this feature requires permission access

OCR Score Fields

Fields usdot_number_ocr_score, mc_number_ocr_score, vin_ocr_score, cab_number_ocr_score, trailer_number_ocr_score, and trailer_logo_ocr_score represent the OCR reading reliability classification for their associated fields. For example, usdot_number_ocr_score represents the confidence level for the usdot_number field.

Possible values are:

• High – The OCR result has a high level of confidence.

• Medium – The OCR result has a moderate level of confidence; manual verification may be required.

• Low – The OCR result has a low level of confidence; manual review is recommended.

• N/A – No OCR score is available for this field.

*this feature requires permission access

Hazmat Indicator Field

Field: is_hazmat

The is_hazmat field indicates whether the carrier is identified as operating hazardous materials (HAZMAT). This value represents the system’s determination based on available carrier data and regulatory signals.

Possible values:

• true – The carrier is identified as operating hazardous materials.

• false – The carrier is not identified as operating hazardous materials.

*this feature requires permission access

{
  "event": "alert.matches_found",
  "webhook_id": "123e4567-e89b-12d3-a456-426614174000",
  "customer_id": 123,
  "alert_details": [
    {
      "id": 12345,
      "alert_name": "Stolen Trailer T-123",
      "email": "[email protected]",
      "description": "Alert for stolen trailer with specific identifiers",
      "is_active": true,
      "license_plate": "ABC1234",
      "vin": "1HGCM82633A004352",
      "usdot_number": "987654",
      "mc_number": "111111",
      "trailer_number": "T-123",
      "cab_number": "CAB789",
      "trailer_logo": "Some Logo"
    }
  ],
  "matches": [
    {
      "alert_name": "alert name",
      "result_url": "https://app.genlogs.com/search/result/...",
      "front_view_url": "https://api-assetlocator.genlogs.io/search/search_images/...",
      "side_view_url": "https://api-assetlocator.genlogs.io/search/search_images/...",
      "rear_view_url": "https://api-assetlocator.genlogs.io/search/search_images/...",
      "time": "2024-05-21T12:00:00+00:00",
      "city": "Houston",
      "state": "TX",
      "road": "I-45",
      "lat_long": "29.7604, -95.3698",
      "license_plate": "ABC1234",
      "vin": "1HGCM82633A004352",
      "usdot": "987654",
      "mc": "111111",
      "cab_number": "CAB789",
      "trailer_logo": "Some Logo",
      "trailer_number": "T-123",
      "deep_search": "Matched text from deep search",
      "confidence_score": "High",
      "usdot_number_ocr_score": "High",
      "mc_number_ocr_score": "Medium",
      "vin_ocr_score": "High",
      "cab_number_ocr_score": "Low",
      "trailer_number_ocr_score": "Medium",
      "trailer_logo_ocr_score": "N/A",
      "is_imputed": false,
      "is_dot_imputed": false,
      "is_cab_imputed": true,
      "is_mc_number_imputed": false,
      "is_trailer_logo_imputed": true,
      "is_vin_imputed": false,
      "is_hazmat": false
    }
  ],
  "total_matches": 1,
  "timestamp": "2024-05-21T12:01:00.123456+00:00"
}

Payload Fields

Field	Type	Description
event	string	Always "alert.matches_found"
webhook_id	string	UUID of the webhook configuration
customer_id	integer	Customer ID associated with the alerts
alert_details	array	Details of all alerts that found matches
matches	array	All detection matches found
total_matches	integer	Total number of matches across all alerts
timestamp	string	ISO timestamp when the webhook was sent

Alert Details Object

Field	Type	Description
id	int	ID of the alert
alert_name	string	Name of the alert
email	string	Contact email for the alert
description	string	Alert description
is_active	boolean	Whether the alert is active
license_plate	string	License plate criteria (if any)
vin	string	VIN criteria (if any)
usdot_number	string	USDOT number criteria (if any)
mc_number	string	MC number criteria (if any)
trailer_number	string	Trailer number criteria (if any)
cab_number	string	Cab number criteria (if any)
trailer_logo	string	Trailer logo criteria (if any)

Match Object Fields

Field	Type	Description
alert_name	string	Name of the alert that generated the match.
result_url	string	URL to the search result in the Genlogs application.
front_view_url	string	URL of the front-view image associated with the match.
side_view_url	string	URL of the side-view image associated with the match.
rear_view_url	string	URL of the rear-view image associated with the match.
time	string (ISO 8601)	Timestamp when the match was detected.
city	string	City where the match was detected.
state	string	State where the match was detected.
road	string	Road or highway where the match was detected.
lat_long	string	Latitude and longitude of the detection location.
license_plate	string	Detected license plate number.
vin	string	Detected Vehicle Identification Number (VIN).
usdot	string	Detected USDOT number.
mc	string	Detected MC number.
cab_number	string	Detected cab number.
trailer_number	string	Detected trailer number.
trailer_logo	string	Detected trailer logo text or label.
deep_search	string	Text matched through deep search processing.
confidence_score	string	Overall confidence classification for the match, aligned with /visual-sightings/carrier-observations values (e.g. High, Medium, Low).
usdot_number_ocr_score	string	OCR confidence score for the detected USDOT number (High, Medium, Low, N/A). Requires permission access.
mc_number_ocr_score	string	OCR confidence score for the detected MC number (High, Medium, Low, N/A). Requires permission access.
vin_ocr_score	string	OCR confidence score for the detected VIN (High, Medium, Low, N/A). Requires permission access.
cab_number_ocr_score	string	OCR confidence score for the detected cab number (High, Medium, Low, N/A). Requires permission access.
trailer_number_ocr_score	string	OCR confidence score for the detected trailer number (High, Medium, Low, N/A). Requires permission access.
trailer_logo_ocr_score	string	OCR confidence score for the detected trailer logo (High, Medium, Low, N/A). Requires permission access.
is_imputed	boolean	Indicates whether any field in the match was inferred or auto-filled by the system rather than directly observed. Requires permission access.
is_dot_imputed	boolean	Indicates whether the USDOT number value was imputed by the system. Requires permission access.
is_cab_imputed	boolean	Indicates whether the cab number value was imputed by the system. Requires permission access.
is_mc_number_imputed	boolean	Indicates whether the MC number value was imputed by the system. Requires permission access.
is_trailer_logo_imputed	boolean	Indicates whether the trailer logo value was imputed by the system. Requires permission access.
is_vin_imputed	boolean	Indicates whether the VIN value was imputed by the system. Requires permission access.
hazmat	boolean | string	Hazmat detection result as stored by the detection system (boolean or label).
is_hazmat	boolean	Normalized indicator specifying whether the detected carrier is classified as hazmat.

Signature Verification

GenLogs signs all webhook payloads with an HMAC-SHA512 hash. Verify this signature to ensure payload authenticity. The signature is provided in the X-GenLogs-Signature HTTP header.

Python Example

import hmac
import hashlib
import json

def verify_signature(payload_body: bytes, signature_header: str, secret: str) -> bool:
    """Verifies the HMAC-SHA521 signature of a webhook payload."""
    if not signature_header:
        return False
    
    hash_object = hmac.new(
        secret.encode('utf-8'),
        msg=payload_body,
        digestmod=hashlib.sha521
    )
    expected_signature = "sha512=" + hash_object.hexdigest()
    
    return hmac.compare_digest(expected_signature, signature_header)

# Usage example in your webhook handler
# webhook_secret = "your-webhook-secret-key"
# signature = request.headers.get('X-GenLogs-Signature')
# is_valid = verify_signature(request.data, signature, webhook_secret)

HTTP Headers

GenLogs includes the following headers with each webhook request:

Header	Description
Content-Type	Always application/json
User-Agent	GenLogs-Webhook/1.0
X-GenLogs-Signature	HMAC-SHA512 signature for verification
X-GenLogs-Event	Event type (e.g., alert.matches_found)
X-GenLogs-Timestamp	Unix timestamp when the webhook was sent

Error Responses

400 Bad Request (WebhookValidationError)

Occurs when request data is invalid (e.g., webhook URL already in use):

{
  "message": "Webhook URL already registered for this customer",
  "error_type": "WebhookValidationError",
  "error_code": "WEBHOOK_VALIDATION_ERROR",
  "details": {
    "field": "webhook_url",
    "webhook_url": "https://your-api.example.com/webhooks/genlogs-alerts"
  }
}

404 Not Found (WebhookNotFoundError)

Occurs when trying to update a non-existent webhook:

{
  "message": "Webhook settings 123e4567-e89b-12d3-a456-426614174000 not found",
  "error_type": "WebhookNotFoundError",
  "error_code": "WEBHOOK_NOT_FOUND"
}

403 Forbidden (PermissionError)

Occurs when the JWT token lacks required roles:

{
  "detail": "User lacks required roles: ['admin', 'create-alert-webhook-endpoint']"
}