Callbacks API

The Callbacks API lets you register a webhook endpoint that Borderbolt will POST to whenever a customs status event occurs on one of your declarations. Each delivery is signed with HMAC-SHA256 so you can verify it came from Borderbolt.

Required Scope: Any valid API token — no specific scope required.

Register a Callback


POST /api/v1/callbacks/register

Request Body

Field	Required	Type	Description
`callback_url`	Yes	string	HTTPS URL Borderbolt will POST events to
`callback_format`	No	string	Payload format: `json` (default)
`events`	Yes	array	One or more event names to subscribe to (see Event Types)

Example Request


curl -X POST https://app.borderbolt.com/api/v1/callbacks/register \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "callback_url": "https://yoursystem.com/webhooks/borderbolt",
    "callback_format": "json",
    "events": [
      "declaration.accepted",
      "declaration.released",
      "declaration.rejected"
    ]
  }'

Example Response


{
  "id": 42,
  "callback_url": "https://yoursystem.com/webhooks/borderbolt",
  "callback_format": "json",
  "events": ["declaration.accepted", "declaration.released", "declaration.rejected"],
  "callback_secret": "a9f3c2e1b8d7...",
  "created_at": "2026-05-04T10:00:00.000000Z"
}

Save the secret now. The callback_secret is only returned once at registration time. Store it securely — it is used to verify the HMAC signature on every delivery. If you lose it, use Regenerate Secret to get a new one.

List Callbacks

Retrieve all registered callbacks for the current API credential.


GET /api/v1/callbacks

Example Request


curl https://app.borderbolt.com/api/v1/callbacks \
  -H "Authorization: Bearer {token}"

Example Response


[
  {
    "id": 42,
    "callback_url": "https://yoursystem.com/webhooks/borderbolt",
    "callback_format": "json",
    "events": ["declaration.accepted", "declaration.released", "declaration.rejected"],
    "has_secret": true,
    "updated_at": "2026-05-04T10:00:00.000000Z"
  }
]

The has_secret flag indicates whether a secret is set. The secret itself is never returned on list requests.

Delete a Callback

Remove a registered callback endpoint.


DELETE /api/v1/callbacks/{id}

Example Request


curl -X DELETE https://app.borderbolt.com/api/v1/callbacks/42 \
  -H "Authorization: Bearer {token}"

Returns HTTP 204 No Content on success.

Regenerate Secret

Generate a new signing secret for an existing callback. The previous secret is immediately invalidated.


POST /api/v1/callbacks/regenerate-secret

Example Request


curl -X POST https://app.borderbolt.com/api/v1/callbacks/regenerate-secret \
  -H "Authorization: Bearer {token}"

Example Response


{
  "callback_secret": "b2e5f8a3c1d0..."
}

Test Delivery

Send a test event payload to your registered callback URL. Use this to verify your endpoint is reachable and your HMAC verification is working correctly.


POST /api/v1/callbacks/test

Example Request


curl -X POST https://app.borderbolt.com/api/v1/callbacks/test \
  -H "Authorization: Bearer {token}"

Borderbolt will POST a synthetic declaration.status_changed payload to your callback URL and return the HTTP response code your endpoint returned.

Event Types

Subscribe to any combination of the following events:

Event	Triggered when
`declaration.submitted`	Declaration has been submitted to Dutch Customs
`declaration.accepted`	Dutch Customs accepted the declaration (MRN assigned)
`declaration.released`	Goods have been released
`declaration.rejected`	Declaration was rejected by Dutch Customs
`declaration.control`	Declaration selected for physical or documentary control
`declaration.held`	Goods held pending inspection or clarification
`declaration.invalidated`	Declaration has been invalidated
`declaration.status_changed`	Any other status transition

Webhook Delivery

When an event fires, Borderbolt sends an HTTP POST to your registered URL with the following headers:

Header	Description
`X-Borderbolt-Event`	The event name (e.g. `declaration.accepted`)
`X-Borderbolt-Timestamp`	Unix timestamp of the delivery
`X-Borderbolt-Signature`	HMAC-SHA256 signature of the raw JSON body

Verifying the Signature

Compute HMAC-SHA256 over the raw request body using your callback_secret as the key. Compare it to the value in X-Borderbolt-Signature. Reject any delivery where the signatures do not match.


// PHP verification example
$payload   = file_get_contents('php://input');
$secret    = getenv('BORDERBOLT_WEBHOOK_SECRET');
$signature = hash_hmac('sha256', $payload, $secret);
 
if (!hash_equals($signature, $_SERVER['HTTP_X_BORDERBOLT_SIGNATURE'])) {
    http_response_code(401);
    exit;
}


# Python verification example
import hmac, hashlib
 
def verify(payload: bytes, secret: str, header_sig: str) -> bool:
    expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header_sig)

Example Payload


{
  "event": "declaration.accepted",
  "timestamp": "2026-05-04T10:15:00Z",
  "declaration": {
    "id": 12350,
    "reference": "BB202600012350",
    "mrn": "26NL000000123456A1",
    "status": "ACC",
    "declaration_symbol": "IM"
  }
}

Retry Behaviour

If your endpoint returns a non-2xx status code or times out, Borderbolt will retry the delivery up to three times with exponential back-off (30 s, 5 min, 30 min). After all retries are exhausted the delivery is abandoned. Your endpoint should return 200 or 204 as quickly as possible — offload any heavy processing to a background queue.