Webhook Endpoints

Webhook endpoints can be created in your account's Settings section. They allow you to be notified of changes on your Flexport data and milestone events for your shipments.

Set a secret token for each webhook endpoint. Flexport uses this token as the HMAC key to sign each request body. Verify the signature before accepting or processing the webhook.

The payload for a webhook is an Event object.

Flexport sends both of the following signature headers with each request. Use HMAC-SHA256 for new integrations and migrate existing integrations from HMAC-SHA1 to HMAC-SHA256.

Header	Algorithm	Header value format
X-Hub-Signature-256	HMAC-SHA256 (recommended)	sha256= followed by 64 lowercase hexadecimal characters
X-Hub-Signature	HMAC-SHA1 (legacy)	sha1= followed by 40 lowercase hexadecimal characters

HTTP header names are case-insensitive. Your HTTP server or framework may expose them as x-hub-signature-256 and x-hub-signature. Use a case-insensitive header lookup or your framework's normalized header names. The digest is hex-encoded, not base64-encoded, and the algorithm prefix is part of the header value.

To validate a payload using HMAC-SHA256:

1. Read the X-Hub-Signature-256 header. Reject the request if the header is missing or does not contain sha256= followed by exactly 64 lowercase hexadecimal characters.
2. Compute the HMAC-SHA256 digest using your endpoint's secret token as the key and the raw request body bytes as the message. Do not parse and re-serialize the JSON before computing the digest: changes to whitespace, key order, or encoding will change the signature.
3. Encode the computed digest as lowercase hexadecimal.
4. Remove the sha256= prefix from the received header value and compare the remaining digest with your computed digest using a constant-time comparison. Alternatively, prepend sha256= to your computed hexadecimal digest and compare the complete header values in constant time. 5. Accept the webhook only if the signatures match.

For legacy HMAC-SHA1 verification, follow the same steps using X-Hub-Signature, HMAC-SHA1, the sha1= prefix, and a 40-character lowercase hexadecimal digest.

Flexport expects to receive an HTTP 200 response code from your endpoint. We will continue trying to deliver the message a number of times if we don’t receive one. To prevent time outs, it is wise to configure your endpoints to send a 200 and then do any long running processing on the data.