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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.