Callback

Callback types

Two callbacks types are available: Invoice and Payout

• Invoice callback

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

  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 to construct and verify the signature.