Webhook

Tolls Webhook URL

When setting up webhooks in our system for toll notifications, you will be asked to specify a URL where you would like to receive the webhook notifications.

Example Payload

{
  "type": "ticket",
  "ticketID": 1,
  "amount": "10",
  "fee": "0",
  "exit_plaza": "X EXIT PLAZA",
  "exit_plaza_cash_cost": "10",
  "posting_date": "1970-01-01 00:00:00.000000+00:00",
  "trans_date_time": "1970-01-01 00:00:00",
  "vehicle_plate_number": "123456",
  "vehicle_tracking_number": "",
  "vehicle_plate_state": "NY",
  "custom_fields" : {
    "field1": "value1",
    "field2": "value2"
  }
}

Custom Fields are only sent if you have configured them in the webhook settings.

Parking Webhook URL

When setting up webhooks in our system for parking notifications, you will be asked to specify a URL where you would like to receive the webhook notifications.

Example Payload

{
  "type": "ticket",
  "issuing_authority": "X Issuing Authority",
  "violation_number": "1234567890",
  "ticket_type": "Parking",
  "description": "Lorem ipsum dolor sit amet",
  "date": "1970-01-01",
  "time": "00:00:00",
  "vehicle": "123456",
  "vehicle_state": "NY",
  "fine_amount": "10",
  "transfer_of_liability": "False",
  "fleet_liable": "False",
  "pdf": "",
  "custom_fields" : {
    "field1": "value1",
    "field2": "value2"
  }
}

Response Handling

Your endpoint should handle the incoming POST requests and respond with a 200 OK status code to acknowledge the successful receipt of the webhook.

Example Response

{
  "status": "success",
  "message": "Webhook received successfully"
}

Security and Best Practices

Ensure your endpoint is secured using HTTPS.
Ensure you have duplicate logic handling for tickets identificaitons.
Set up error handling to manage different types of webhook events and potential issues with payload processing.

Headers Information

When receiving webhook notifications, the following headers will be sent along with the payload:

Custom Configured Headers

Any headers specified in the webhook configuration settings.

Fleet-Specific Headers

Ext-Client-Id: Provided if available from customer_info.
Ext-Billing-Id: Provided if available from customer_info.

Generic Headers

Fleet-Id: The fleet ID associated with the webhook.
X-Timestamp: A UNIX timestamp of when the webhook was sent.
X-Signature: An HMAC SHA-256 signature generated using a secret key, the payload, and the timestamp for security verification.

Signature in Webhooks

To ensure the security and authenticity of the webhook notifications, a signature is generated and included in the headers of each webhook request. This signature allows the receiving endpoint to verify the integrity of the payload.

How the Signature is Generated

The signature is created using an HMAC SHA-256 hashing process that involves the following components:

Secret Key: The webhook_signature_secret_token from your active webhook integration.
Data: The payload of the webhook.
Timestamp: The UNIX timestamp representing when the webhook was sent.

The signature is generated using the following Python code:

import json
import hmac
import hashlib

def generate_signature(secret_key, data, timestamp):
    serialized_payload = json.dumps(data, separators=(',', ':'))
    signed_payload = f"{timestamp}.{serialized_payload}"
    signature = hmac.new(secret_key.encode(),
                         signed_payload.encode(), hashlib.sha256).hexdigest()
    return signature

Obtaining the Secret Key

The secret key required for signature verification can be obtained from the Fleet Active Integrations API. After creating a webhook integration, the integration details will include the webhook_signature_secret_token field.

Example Response from Fleet Active Integrations:

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 121,
      "integration": 4,
      "enabled": true,
      "data": {
        "auth": {
          "url": "https://webhook.site/1b064192-833f-41ff-99e0-a2e32044035f"
        },
        "urls": {},
        "config": {},
        "documentation": "https://docs.api.example.com/#9ca0ff12-d3d8-4339-b2a0-48b5477f3b62"
      },
      "documentation": "https://docs.api.example.com/#9ca0ff12-d3d8-4339-b2a0-48b5477f3b62",
      "webhook_signature_secret_token": "dummy_token"
    }
  ]
}

The webhook_signature_secret_token field contains the secret key that should be used for signature verification.

Introduction

Integration Guides

Driver Billing

Auth

Vehicles

Fleet

Parking

Transponders

Tolls

Documents

Integrations

Drivers

Billing

Support Tickets

Stats

Tolls Webhook URL

Example Payload

Parking Webhook URL

Example Payload

Response Handling

Example Response

Security and Best Practices

Headers Information

Custom Configured Headers

Fleet-Specific Headers

Generic Headers

Signature in Webhooks

How the Signature is Generated

Obtaining the Secret Key

Example Response from Fleet Active Integrations:

​Tolls Webhook URL

​Example Payload

​Parking Webhook URL

​Example Payload

​Response Handling

​Example Response

​Security and Best Practices

​Headers Information

​Custom Configured Headers

​Fleet-Specific Headers

​Generic Headers

​Signature in Webhooks

​How the Signature is Generated

​Obtaining the Secret Key

​Example Response from Fleet Active Integrations:

Tolls Webhook URL

Example Payload

Parking Webhook URL

Example Payload

Response Handling

Example Response

Security and Best Practices

Headers Information

Custom Configured Headers

Fleet-Specific Headers

Generic Headers

Signature in Webhooks

How the Signature is Generated

Obtaining the Secret Key

Example Response from Fleet Active Integrations: