Webhooks notify your application in real time whenever a status change occurs. Instead of polling the API, you receive an HTTP POST request to your endpoint with the updated data.
Available webhooks Webhook Triggered when Customer Customer verification status changes On-ramp On-ramp transaction status changes Off-ramp Off-ramp transaction status changes Transfer Transfer transaction status changes Payment Payment status changes Q1/2026
Setting up webhooks To configure webhooks, go to the Dashboard and add your endpoint URL.
You must be a project admin or owner to create webhooks.
Payload examples Each webhook delivers a JSON payload to your endpoint. The structure varies by webhook type.
Customer
On-ramp
Off-ramp
Transfer
Triggered when customer verification status changes (e.g., NOT_STARTED → UNDER_VERIFICATION → APPROVED). { "customerId" : "aded1bd6-c778-455a-a437-5f8703842f1d" , "status" : "UNDER_VERIFICATION" , "level" : "STANDARD" }
Triggered when on-ramp transaction status changes (e.g., AWAITING_FUNDS → TRANSFERRING_FIAT → TRADING → TRANSFERRING_STABLECOIN → SUCCESS). { "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" }
Triggered when off-ramp transaction status changes (e.g., TRANSFERRING_STABLECOIN → TRADING → TRANSFERRING_FIAT → SUCCESS). { "id" : "c226ea0b-879c-409c-a4db-cb22f4b380a0" , "customerId" : "f2671460-ef3f-4833-bf0d-4969cfda1a34" , "type" : "OFF_RAMP" , "request" : { "sourceCurrency" : "USDC" , "targetCurrency" : "BRL" , "sourceAmount" : "2.810000" , "payment" : { "rail" : "PIX" , "keyValue" : "16286876731" , "keyType" : "CPF" } }, "state" : { "status" : "SUCCESS" , "payment" : { "rail" : "PIX" , "keyValue" : "16286876731" , "keyType" : "cpf" }, "receipt" : { "sourceCurrency" : "USDC" , "sourceAmount" : "2.810000" , "targetCurrency" : "BRL" , "baseExchangeRate" : "3.808929" , "baseTargetAmount" : "10.70" , "fees" : { "lumx" : { "rate" : "10" , "flatAmount" : "1.000000" , "totalAmount" : "1.002810" , "currency" : "USDC" }, "partner" : { "id" : "759df1ec-0ce6-45ec-aaec-25cdafa1e5ea" , "rate" : "1" , "flatAmount" : "0.000000" , "totalAmount" : "0.000281" , "currency" : "USDC" } }, "finalTargetAmount" : "6.88" , "finalExchangeRate" : "2.449248" , "transactionHash" : "0x84ab706f0b152a19cc151c191bdc218a7e5600b7c02289fe07a5f36a56123812" , "blockExplorerUrl" : "https://arbiscan.io/tx/0x84ab706f0b152a19cc151c191bdc218a7e5600b7c02289fe07a5f36a56123812" } }, "createdAt" : "2025-08-24T17:22:45.441Z" , "updatedAt" : "2025-08-24T17:23:15.093Z" }
Triggered when transfer transaction status changes (e.g., PROCESSING → SUCCESS). { "id" : "e53f8b01-e514-4d52-b3c5-1a83b729bf13" , "customerId" : "715fc46a-efcc-4969-a8f9-f38fe65c6aa0" , "type" : "TRANSFER" , "request" : { "currency" : "USDC" , "from" : "715fc46a-efcc-4969-a8f9-f38fe65c6aa0" , "to" : "f2671460-ef3f-4833-bf0d-4969cfda1a34" , "amount" : "2" }, "state" : { "status" : "SUCCESS" , "receipt" : { "transactionHash" : "0x436fa0d4ce473e4c49dff4e01034e484fa6a51330304a93147592e352ae690b4" , "blockExplorerUrl" : "https://arbiscan.io/tx/0x436fa0d4ce473e4c49dff4e01034e484fa6a51330304a93147592e352ae690b4" } }, "createdAt" : "2025-08-24T17:46:53.078Z" , "updatedAt" : "2025-08-24T17:46:55.145Z" }
Verifying webhook signatures Lumx signs each webhook request with a X-Hub-Signature header. Verify this signature to confirm the request is authentic.
Get your webhook secret
Copy the secret from your webhook settings in the Dashboard.
Compute the signature
Generate a HMAC-SHA256 hash using:
Key : Your webhook secretMessage : The raw request body (stringified payload)Encoding : hex
Compare signatures
Compare your computed signature with the X-Hub-Signature header value. If they match, the request is authentic.
