API Reference

Callback(s) Authentication process

This page describe the Authentication processes available for Booking and Tracking Callback of CargoCONNECT API suite

Authentication

To enhance security, our system supports authentication for both Tracking and Booking update callback. Customers can choose from the following authentication methods, depending on their integration requirements:

1. Basic Authentication

This method uses a username and password encoded in Base64. The credentials will be included in the Authorization header of each webhook event send to your system.

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

⚠️ We will ask you to provide username and password needed for Basic Authentication

2. Bearer Token

Bearer authentication uses a static token to validate requests. The credentials will be included in the Authorization header of each webhook event send to your system.

Authorization: Bearer YOUR_API_TOKEN

⚠️ We do not handle dynamic token for the moment.

3. HMAC Signature

HMAC (Hash-Based Message Authentication Code) provides a secure way to verify webhook event integrity and authenticity.

With this method:
Each update will include A header cargoai-api-key containing a Base64-encoded HMAC SHA256 signature of the request payload, generated using your API key as the secret.

🧠 How the Signature is Generated

To generate the cargoai-api-key header on our side, we:

  • Use your API key (from x-api-key) as the HMAC secret.
  • Take the raw payload of the request body (as bytes).
  • Compute an HMAC using SHA-256.
  • Base64-encode the result.
  • Add it as the value of the cargoai-api-key header.

✅ How to Verify the Signature (on your side)

To ensure a request is valid:

  • Retrieve the cargoai-api-key headers from the request.
  • Use your x-api-key as the secret.
  • Recompute the HMAC using the raw request body.
  • Base64-encode your result.
  • Compare it with the value in cargoai-api-key.

If they match, the request is authentic.

🔧 Enabling Authentication

Authentication is optional and disabled by default. To enable authentication for your integration:

➡️ Please contact our team directly so we can configure the preferred method for your account and provide any necessary credentials or secrets.