# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.thedex.cloud/introduction/callback.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.