### 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 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.