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

{
  "event": "alert.matches_found",
  "webhook_id": "123e4567-e89b-12d3-a456-426614174000",
  "customer_id": 123,
  "alert_details": [
    {
      "id": "456e7890-e12b-34d5-a678-426614174111",
      "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"
    }
  ],
  "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	string	UUID 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
result_url	string	URL to view the full search result
front_view_url	string	URL to the front view image
side_view_url	string	URL to the side view image
rear_view_url	string	URL to the rear view image
time	string	ISO timestamp when the truck was detected
city	string	City where the detection occurred
state	string	State/province code
road	string	Road or highway name
lat_long	string	GPS coordinates as "latitude, longitude"
license_plate	string	Detected license plate number
vin	string	Vehicle identification number
usdot	string	USDOT number
mc	string	MC number
cab_number	string	Cab number
trailer_logo	string	Detected trailer logo text
trailer_number	string	Trailer number
deep_search	string	Matched text from deep search analysis

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