Webhooks Guide
Webhooks allow you to receive real-time HTTP notifications when events occur in your LuxCore account, such as when a payment completes or fails.How Webhooks Work
1
Event Occurs
A payment status changes (e.g., completed, failed)
2
LuxCore Sends Notification
We send an HTTP POST request to your configured endpoint
3
You Process the Event
Your server processes the event and returns a 2xx response
4
Retry if Needed
If delivery fails, we retry with exponential backoff
Setting Up Webhooks
Create a Webhook Endpoint
Response
Webhook Events
Withdrawal-type payments (
withdrawal, withdrawal_pp) use the same
payment.* events as deposits. The payout.* events from the initial release
have been merged into the payment.* event namespace.Webhook Payload
All webhook payloads follow this envelope structure:Payment Fields Reference
Amount, Fee, and Net Amount
All monetary values are integers in minor units (centavos). The fee is automatically calculated based on your merchant commission rate.Formula:
net_amount = amount - feeDeposit example (customer pays 1000.50 ARS, merchant fee 4.5%):amount:100050— the amount the customer paidfee:4502— commission charged (100050 × 4.5%)net_amount:95548— amount credited to your balance
amount:50000— the payout amount sent to the recipientfee:2500— commission charged (50000 × 5%)net_amount:47500— recorded net amount; do not use it as the total withdrawal debit
Withdrawal Payload Example
For withdrawals, the payload includespayout details inside customer_data:
customer_data Fields
Thecustomer_data object contains the following documented fields when available:
Webhook Headers
Each webhook request includes these headers:Do not depend on
X-Webhook-Event or X-Webhook-Retry to identify a
notification. Payment examples use data.payment.status; subscriptions use
the event names listed above. Skip business actions when X-Webhook-Test is
true.Signature Verification
Always verify webhook signatures to ensure requests are from LuxCore.Signature Format
Verification Algorithm
Implementation Examples
The examples below verify the default HMAC-SHA256 algorithm and process payment notifications only. For HMAC-SHA512, use SHA-512 and thehmac_sha512= prefix agreed for your webhook. Verify a delivery with the test endpoint before enabling order fulfilment. Persist event IDs before applying business effects.
Replay Protection
In addition to signature verification, implement these measures to prevent replay attacks:- Check timestamp: Reject webhooks with timestamps older than 5 minutes (already shown in verification examples above)
- Store webhook IDs: Save the envelope event
idand acknowledge duplicates without applying them again. This prevents replayed webhooks within the timestamp window - Distinguish retries from replays: Legitimate retries from LuxCore will have the same
X-Webhook-Id. Only process each unique webhook ID once
The combination of timestamp validation and webhook ID deduplication provides
strong replay protection.
Retry Policy
Webhook delivery is at least once. Save the body envelope’s eventid when processing a delivery: retries of that event retain the same id and created_at. A changed payment snapshot receives a different event id, even when its event type matches an earlier notification. Deduplicate by event id before applying business effects; payment ID and event type alone do not identify a delivery.
Delivery retries are bounded by the webhook configuration. max_retries is the total attempt budget, including the first delivery; its default is 3, so the default permits one initial delivery and up to two retries. The configured delivery timeout defaults to 30 seconds.
Retries are delayed rather than sent immediately. With the default settings, the first two retry delays can be up to roughly one and two minutes; actual timing varies. Do not depend on an exact schedule. Failed events can be retried using the retry endpoint; retry deliveries retain the same event id and must be deduplicated.
Testing Webhooks
Send a test event to verify your endpoint:X-Webhook-Signature, X-Webhook-Id, X-Webhook-Timestamp, and X-Quadpay-Secret-Version.
Managing Webhooks
List Webhooks
Update Webhook
Delete Webhook
In-Request Webhooks
Instead of pre-configuring webhooks via the API, you can pass awebhook_url directly in the payment creation request. This is useful when you want per-payment notification routing or a simpler integration without managing webhook endpoints.
Usage
- Include
webhook_urlin yourPOST /paymentsrequest - Choose notification types with the optional
webhook_eventsarray - Receive signed notifications at the specified URL and verify them with the signing secret issued for your merchant
Example
Default Events
Ifwebhook_events is not provided, the following events are subscribed by default:
payment.createdpayment.completedpayment.failedpayment.refunded
Signing and Repeated Deliveries
Use the webhook signing secret issued for your merchant and confirm it with a test delivery before enabling business actions. Creation and test responses do not return signing secrets. Coordinate secret rotation with support. Verify the raw body, timestamp and signature for every delivery. Save the eventid to avoid applying the same notification twice, including when the same URL is used for several payments.
Ordering and Deduplication
Notifications can arrive more than once or out of order. Store the envelopeid before applying business effects and acknowledge an already processed delivery with a successful response. For payment notifications with status_version, compare it with the last processed version for that payment before applying an older snapshot.
Keep payment IDs, merchant references and event IDs in your records. Use the payment status endpoint to reconcile a missing or uncertain result. Test notifications (X-Webhook-Test: true) must never trigger fulfilment or balance changes.