Our Webhook system provides updates on the status of transactions, ensuring seamless integration with your application. This system sends HTTPS POST requests to a specified URL.

Creating webhooks

To create a webhook, head to the dashboard, select the project and create your webhook.

You need to be an project admin or owner to create a webhook.

Events

The webhook will be triggered for every asynchronous status change.

Called when the transaction first enters the awaiting_funds status from processing. The second call will be triggered when the transaction moves from awaiting_funds to success or failed.

Webhook payload

Here is an example of the payload delivered to your webhook URL when using both on-ramp and off-ramp:

{
	"id": "86030912-a5fc-4351-b596-0cfaf766b638",
	"customerId": "77e04882-c54e-4203-afd9-d0d963598dc5",
	"type": "on_ramp",
	"request": {
		"amount": "15",
		"payment": {
			"rail": "pix"
		},
		"sourceCurrency": "BRL",
		"targetCurrency": "USDC"
	},
	"state": {
		"status": "success",
		"payment": {
			"rail": "pix"
		},
		"receipt": {
			"fees": {
				"lumx": {
					"flat": "1.500000",
					"percentage": "0.000752"
				},
				"total": "1.530902",
				"currency": "USDC",
				"developer": {
					"flat": "0.030000",
					"percentage": "0.000150"
				}
			},
			"rate": "0.0656",
			"blockchain": {
				"transactionHash": "0xc30abe7bc2c90c90a5ab0cb5666a752a1d87c811ac8e24aa031037bb9df23b68",
				"blockExplorerUrl": "https://amoy.polygonscan.com/tx/0xc30abe7bc2c90c90a5ab0cb5666a752a1d87c811ac8e24aa031037bb9df23b68"
			},
			"sourceAmount": "15",
			"targetAmount": "0.984648",
			"sourceCurrency": "BRL",
			"targetCurrency": "USDC"
		}
	},
	"createdAt": "2025-03-20T13:49:44.209Z",
	"updatedAt": "2025-03-20T13:55:52.610Z"
}

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