> For the complete documentation index, see [llms.txt](https://docs.thedex.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thedex.cloud/introduction/callback.md).

# Callback

## Callback types

Two callbacks types are available: **Invoice** and **Payout**

* [**Invoice callback**](/introduction/callback/invoice.md)
* **Payout callback**

Callbacks are sent to your server to notify you of specific events, such as invoice  or payout status updates.

## Configuration

To enable callback functionality, the URL must be defined in one of the following ways:

* **User-level configuration**:\
  Set the `callbackUrl` field in your user profile in the Thedex merchant settings.
  1. Sign in at [app.thedex.cloud](https://app.thedex.cloud).
  2. After logging in, navigate to the **"Merchants"** section.
  3. Click the **"Edit Settings"** button.
  4. Fill in **Callback Url**
  5. Complete form.
* **Per-request configuration**:\
  If not set at the merchant level, you can specify `callbackUrl` directly in your **API request** when creating an invoice.

> If both options are used, the values passed in the API request will override the user defaults

## Verifying Incoming Webhooks

To ensure the authenticity of incoming webhook (callback) requests, you must verify the headers included with each callback:

* `X-EX-APIKEY`: The API key of the **merchant**
* `X-EX-PAYLOAD`: Base64-encoded JSON body of the callback
* `X-EX-SIGNATURE`: HMAC SHA-512 signature generated from the payload using your **secret key**

These headers are used to confirm that the callback was generated by Thedex and that the payload has not been altered.

### Verification Steps

1. **Validate the API key**:\
   Compare the `X-EX-APIKEY` header with your own API key stored in your system.\
   This ensures the callback is intended for your merchant account.
2. **Reconstruct the signature**:
   * Take the raw JSON body of the request.
   * Encode it in Base64.
   * Use your **secret key** to generate an HMAC SHA-512 signature from the Base64 payload.
3. **Compare the signatures**:
   * Match your generated signature with the `X-EX-SIGNATURE` header.
   * If they match — the callback is valid.
   * If they don't match — reject the request as potentially compromised.

You can follow [this method](/documentation/api-overview.md#how-to-generate-the-signature) to construct and verify the signature.