Start your integration with the v3 API now.

Getting started with the v3 API
Authenticating with the v3 API
Using the v3 API in test mode
Placing an order with the v3 API
Managing event subscriptions in the v3 API
Retrieving shipping documents with the v3 API
Retrieving tracking updates with the v3 API
Cancelling a v3 API shipping order
Making a quote request with the v3 API
Retrieving the list of transport offer codes for the v3 API
Retrieving the list of content categories with the v3 API
Retrieving the list of proximity points with the v3 API

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.

Articles that might interest you

Retrieving shipping documents with the v3 API
Retrieving tracking updates with the v3 API