Webhooks are a way to receive events from all Lumx updates. This means that for every customer and every transaction event, you will receive all the data in real time.

Creating webhooks

Before creating a webhook, you need to:
  1. Create an account on Lumx
  2. Create a project
Now you can go to the Dashboard, select a project, and go to the Settings page. From there, click on the Webhooks tab.
You need to be a project admin or owner to create a webhook.

Events

The webhook will be triggered for every status change.
Called when the transaction first moves from awaiting_funds status to
transferring_fiat. Then, follows the order of events below:
transferring_fiattradingtransferring_stablecoinsuccess/failedFor a comprehensive guide to On-ramp transactions, refer to the guide.

Webhook payload

Here is an example of the payload delivered to your webhook URL when receiving an on-ramp event:
Payload
{
  "id": "51b7698b-b9a8-409f-8ad0-35114a85b0f3",
  "customerId": "f2671460-ef3f-4833-bf0d-4969cfda1a34",
  "type": "on_ramp",
  "request": {
    "sourceCurrency": "BRL",
    "targetCurrency": "USDC",
    "sourceAmount": "30.00",
    "payment": {
      "rail": "PIX"
    }
  },
  "state": {
    "status": "success",
    "payment": {
      "rail": "PIX",
      "brCode": "00020101021226790014br.gov.bcb.pix2557brcode.starkinfra.com/v2/55528a2bddd749bcba0fda0dea6721765204000053039865802BR5909Lumx S.A.6014Rio de Janeiro62070503***63041488"
    },
    "receipt": {
      "sourceCurrency": "BRL",
      "sourceAmount": "30.00",
      "targetCurrency": "USDC",
      "baseExchangeRate": "0.180721",
      "baseTargetAmount": "5.421630",
      "fees": {
        "lumx": {
          "rate": "15",
          "flatAmount": "1.000000",
          "totalAmount": "1.008132",
          "currency": "USDC"
        },
        "partner": {
          "id": "759df1ec-0ce6-45ec-aaec-25cdafa1e5ea",
          "rate": "1",
          "flatAmount": "0.000000",
          "totalAmount": "0.000542",
          "currency": "USDC"
        }
      },
      "finalTargetAmount": "4.412955",
      "finalExchangeRate": "0.147098",
      "transactionHash": "0xff00c9fcebfd5d030fb837630b2584c3db23e0f08d238a8fd421f74d64f2dcbf",
      "blockExplorerUrl": "https://arbiscan.io/tx/0xff00c9fcebfd5d030fb837630b2584c3db23e0f08d238a8fd421f74d64f2dcbf"
    }
  },
  "createdAt": "2025-08-24T17:41:40.182Z",
  "updatedAt": "2025-08-24T17:43:17.111Z"
}

Security

The API signs the event by adding a X-Hub-Signature header to the request. This signature can be used to verify the authenticity of the request by following the steps below:
1

First Step

Go to the webhook settings page and copy the secret.
2

Second Step

Compute a HMAC-SHA256 hash of the payload using the secret as the key and the stringified payload as the message. The decoding algorithm is hex.
3

Third Step

Compare the generated signature with the one received in the X-Hub-Signature header.