Authentication

To enhance security, our system supports authentication for Tracking, Booking, FlyWINDOW and FWB&FHL update callbacks. 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=

⚠️ You provide the username and password needed for Basic Authentication (in the CargoCONNECT portal, or to our team for legacy API keys)

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:

CargoCONNECT API keys: set it yourself in the CargoCONNECT portal under Settings > Callbacks (organisation owner or admin). For each callback (Tracking subscription updates, Booking & FlyWINDOW, eAWB) choose the method: None, API Key HMAC, Basic Auth or Bearer Token. A setting can apply to the whole organisation, to one API key, to one callback endpoint, or to one API key on one endpoint. The most specific setting wins.

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