Skip to main content

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