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

Manually from the Asset Locator UI using the “ Run Alert Summary ” button.
Programmatically by calling the /run endpoint from the API.
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 aspects

Separate Management: Webhooks and alerts are managed independently
Consolidated Notifications: Receive one payload with all matches from each one of 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
Image URL expiration: Expiration date to consult the URLs to view the truck images (front, side and rear) is one month
Companywide notifications: Webhooks are called for each of the alerts, regardless of the user that created the alert
Multiples webhooks support: Company can set multiple webhook urls
Webhook management: Customer can create, edit, delete and get list of webhook urls

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

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.

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.