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:

Event type	Description
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.

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, you need to have a Loadsmart Application registered. To obtain your credentials, head to the Authentication & Authorization documentation.

After you obtain your credentials, follow these steps:

1. Develop and deploy your webhook endpoint following the guidelines above.
2. 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)
3. Loadsmart Support will configure your webhook subscription;
4. Once your subscription is active, you will start receiving webhook events at your endpoint.

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.