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 configure your webhook
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_FIAT → TRADING → TRANSFERRING_STABLECOIN → SUCCESS/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.