Start your integration with the v3 API now.
Managing event subscriptions in the v3 API
The v3 API uses webhooks to notify you of specific events related to shipping orders.
Subscription
To use webhooks, you first need to create subscriptions to each event type you want to follow. Subscription can be done via the developer app interface or this API via the GET /v3.1/subscription, POST /v3.1/subscription, PUT /v3.1/subscription/{id}, DELETE /v3.1/subscription/{id} endpoints.
When you subscribe to a type of event, each time an event of this type occurs, a request will be sent to the URL you provided at subscription.
A subscription made with a v3 API application will only receive events related to shipping orders created through the same application.
Authentication
You can ensure that the request comes from Boxtal by checking the value of the x-bxt-signature
header, which should have a value equal to the HMAC SHA256 encoding of the JSON body, using the webhook validation key linked to your subscription as a secret. We strongly recommend that you use this to authenticate requests.
Code example to check the signature:
# function to verify signature. secret_key is equal to the webhook secret attached to your webhook subscription
FUNCTION verify_signature(http_request, secret_key):
# Extract the signature from the HTTP header
signature_header = http_request.headers.get("x-bxt-signature")
IF signature_header IS NULL:
RETURN FALSE, "Missing signature header"
# Extract the JSON payload from the HTTP request body
payload_json = http_request.body
IF payload_json IS NULL OR payload_json IS empty:
RETURN FALSE, "Empty payload"
# Compute the HMAC SHA256 signature of the payload using the secret key
computed_signature = HMAC_SHA256(payload_json, secret_key)
# Compare the computed signature with the received signature
IF computed_signature EQUALS signature_header:
RETURN TRUE, "Signature verified"
ELSE:
RETURN FALSE, "Signature mismatch"
END IF
END FUNCTION
# function to authenticate http requests. secret_key is equal to the webhook secret attached to your webhook subscription
FUNCTION handle_http_request(http_request, secret_key):
# Verify the HTTP POST request signature
signature_valid, verification_message = verify_signature(http_request, secret_key)
IF signature_valid IS TRUE:
# Parse the JSON payload
parsed_payload = PARSE_JSON(http_request.body)
IF parsed_payload IS NULL:
RETURN HTTP_RESPONSE(400, "Invalid JSON payload")
# Perform the desired actions with the parsed payload
# ... (Your application logic here) ...
# Return a success response
RETURN HTTP_RESPONSE(200, "OK")
ELSE:
# Signature is invalid, return an error response
RETURN HTTP_RESPONSE(401, verification_message)
END IF
END FUNCTION
Response and retries
When receiving a request you have to respond with the standard HTTP status code (2xx for success) in less than 2 seconds.
Any other code will result in a retry process:
- 3 retries every 60 second: t0 + 60s, t0 + 120s, t0 + 180s
- 3 retries every hour: t0 + 1h, t0 + 2h, t0 + 3h
- 1 retry after 6h: t0 + 6h
- 1 retry after 12h: t0 + 12h
- 1 retry after 24 hour: t0 + 24h
After these 10 attempts, the event would be discarded.
If a webhook subscription fails to process 100 events, it will be automatically disabled and should be enabled manually.
Event types
There are 2 event types:
- When a shipping document is created.
- When the tracking of a shipment has changed.