# Callback

## Callback types

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

* [**Invoice callback**](https://docs.thedex.cloud/introduction/callback/invoice)
* **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](https://docs.thedex.cloud/documentation/api-overview#how-to-generate-the-signature) to construct and verify the signature.