# Register callback URLs

> Register the Merchant Callback endpoints that Bolt calls during checkout.

Source: https://help.boltapp.com/platforms/how-to-integrate/set-up-hook-urls

Register each callback only after its endpoint returns the envelope described in [Merchant Callback conventions](/api-reference/merchant-callback/conventions).

<Warning>
  Merchant Callbacks and transaction webhooks use separate URLs. Complete this page under **Administration > API > Merchant Callbacks**. Configure transaction webhooks in the next server-integration task.
</Warning>

<span id="how-to-set-up-hook-urls" />

## Register callback URLs [#register-callback-urls]

1. Sign in to the Bolt Merchant Dashboard for the environment you are testing.
2. Go to **Administration > API** and find **Merchant Callbacks**.
3. Select the division used by your publishable key.
4. Select **Add Callback**, then choose the callback type for the endpoint you implemented.
5. Enter the public HTTPS URL and save it.
6. Repeat for each callback your checkout needs.

The dashboard shows only the callback types enabled for the selected division. If a type you need is missing, ask Bolt to confirm the division's callback configuration.

## Choose a registration method [#choose-a-registration-method]

Use one of the methods available for your division:

* **Universal Merchant API:** Register one URL for every Merchant Callback. Route each request using its top-level `event` value.
* **Individual callbacks:** Register a separate URL for **Create Order**, **Shipping**, **Tax**, or another callback type exposed for the division.

In either case, verify the HMAC signature over the raw request body and return the matching `{ event, status, data }` envelope.

### Universal API URL [#universal-api-url]

When **Universal Merchant API** is available, one public HTTPS URL can receive all Merchant Callback events. The public callback API identifies this registration type as `universal_merchant_api`.

The combined shipping-and-tax URL is different. It is a legacy division setting exposed as **Shipping and Tax** in the dashboard. The public `POST /v1/merchant/callbacks` contract does not accept `shipping_and_tax`, and `GET /v1/merchant/callbacks` does not return it. Configure and verify that URL in the dashboard.

If your backend uses Python, the beta [Bolt Python SDK](https://github.com/BoltApp/Bolt-Python-SDK/blob/main/docs/sdks/configuration/README.md#set_merchant_callbacks) wraps the standard callback API as `configuration.set_merchant_callbacks()` and `configuration.get_merchant_callbacks()`. It cannot configure or retrieve the combined shipping-and-tax URL because that URL is outside the public callback API.

<span id="php-example" />

<span id="shipping-url" />

<span id="tax-url" />

<span id="shipping-and-tax-url" />

<span id="create-order-url" />

## Verify registration [#verify-registration]

1. Send a test request to each public endpoint and confirm it returns the expected response envelope.
2. Confirm signature verification uses the raw request body and your signing secret.
3. Call `GET /v1/merchant/callbacks` with the division ID and confirm each standard callback URL appears.
4. For a combined shipping-and-tax URL, confirm the saved value in the dashboard instead.

The [prerequisites guide](/custom-cart/prerequisites#find-your-division-id) explains how to find the division ID and query the registered callbacks.