Getting Started with Webhooks

Webhooks provide a powerful way to receive real-time updates about events in the Loadsmart system. Instead of repeatedly polling our API for changes, you can subscribe to specific events. When these events occur, Loadsmart will send HTTP POST requests to an endpoint you configure in your application. This approach significantly improves scalability and reduces unnecessary API calls.

Available Webhook Events

Currently, you can subscribe to the following event:

• shipment:rate_requested: Triggered when a new shipment is created and a rate is requested.

We are continuously expanding our webhook offerings. Check back regularly for updates on new event types.

Event Payload Structure

When an event occurs, Loadsmart will send a POST request to your configured endpoint with a JSON payload. Here's a breakdown of the payload structure:

Field	Type	Description
event_type	string	The type of event being described. Possible values: shipment:rate_requested
data	object	Contains all the detailed information about the event
data.rate_request_id	string	An identifier of the request that should be responded to
data.notes	string	Notes from the Shipper to the Carrier.
data.mode	string	Shipment mode. Possible values (other modes will be supported soon): FTL
data.weight	string	The weight in lbs of the load
data.equipment_type	string	Type of equipment needed for the shipment. Possible values: DRV, RFR, FBE
data.carrier	object	Information about the carrier
data.carrier.uuid	uuid	Carrier identifier in Loadsmart's system
data.shipper	object	Information about the shipper
data.shipper.uuid	uuid	Shipper identifier in Loadsmart's system
data.stops	array	An array of objects with the attributes listed below
data.stops[].address	string	Address of the stop.
data.stops[].city	string	City of the stop
data.stops[].state	string	State or province of the stop
data.stops[].country	string	Country of the stop. It should be ISO 3166-1 alpha-3 country codes (examples: USA, CAN)
data.stops[].zipcode	string	Postal or ZIP code of the stop
data.stops[].type	string	Type of stop. Possible values: pickup, delivery
data.stops[].index	integer	Identifies the order of the stop in the shipment route, starting with 0 as the first stop
data.stops[].date	string	The date for the first stop activity to occur. The first stop (index = 0) will always have a stop date, but it is optional for other indexes

Setting Up Your Webhook Endpoint

To receive webhook events, you need to set up an endpoint in your application that can handle incoming HTTP POST requests. Here are some key considerations:

1. Your endpoint should be able to process HTTP POST requests.
2. It should return a 2xx status code (preferably 200 OK) to acknowledge receipt of the webhook.
3. If your endpoint returns a non-2xx status code, Loadsmart will consider the delivery failed and will retry the webhook.
4. Implement proper error handling and logging in your endpoint to troubleshoot any issues.
5. Ensure your endpoint can handle concurrent requests, as multiple webhooks may be sent simultaneously.

Subscribing to Webhooks

To subscribe to webhook events, follow these steps:

1. Develop and deploy your webhook endpoint following the guidelines above.
2. Contact Loadsmart Support to request webhook access for your account.
3. Provide the following information to Loadsmart Support:
   • The URL of your webhook endpoint
   • The events you want to subscribe to (e.g., shipment:rate_requested)
   • Any IP restrictions for added security (optional)
4. Loadsmart Support will configure your webhook subscription and provide you with a unique Client ID and Client Secret.
5. Store these credentials securely; you'll need them to validate incoming webhooks.

Note: We are developing a Webhooks API that will allow you to manage your subscriptions programmatically. This feature will be available in the near future, enabling you to add, modify, or remove subscriptions without contacting support.

Validating Webhook Signatures

To ensure the authenticity of incoming webhooks and prevent potential security issues, Loadsmart signs each webhook request. Here's how to validate the signature:

1. Loadsmart includes a signature in the X-Loadsmart-Signature header of each webhook request.
2. The signature is a SHA-256 hash of the concatenated string of your Client Secret and the entire request body, represented as a hexadecimal digest.
3. To validate the signature:
   • Extract the X-Loadsmart-Signature header from the incoming request.
   • Compute the SHA-256 hash of the concatenated string of your Client Secret and the raw request body.
   • Compare your computed hash with the received signature. They should match exactly.

Here's a Python example of how to validate the signature:

import hashlib

def is_valid_signature(payload_body, secret, signature):
    computed_signature = hashlib.sha256(
        (secret + payload_body).encode('utf-8')
    ).hexdigest()
    return computed_signature == signature

# Usage
client_secret = 'your_client_secret_here'
received_signature = request.headers.get('X-Loadsmart-Signature')
is_valid = is_valid_signature(request.data, client_secret, received_signature)

if is_valid:
    # Process the webhook
else:
    # Reject the webhook

By validating the signature, you can ensure that the webhook request is genuinely from Loadsmart and hasn't been tampered with during transmission.

Remember to keep your Client Secret secure and never expose it in client-side code or public repositories.