Skip to main content

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

Obtain the signing secret during onboarding or through support. The webhook creation response does not return the secret; verify a test delivery before processing payment notifications.

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:
Field name differences: The webhook payment object uses different field names than the payment creation API response. Key differences:
  • Webhook: id → API response: transaction_id
  • Webhook: fee → API response: fee_amount
  • Webhook: net_amount → present in both (same name)
Make sure your webhook handler uses the correct field names from the webhook payload.

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 paid
  • fee: 4502 — commission charged (100050 × 4.5%)
  • net_amount: 95548 — amount credited to your balance
Withdrawal example (payout of 500.00 ARS, merchant fee 5%):
  • amount: 50000 — the payout amount sent to the recipient
  • fee: 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 includes payout details inside customer_data:

customer_data Fields

The customer_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

Important: Always compute the HMAC on the raw request body bytes exactly as received, not on re-serialized JSON. Re-serializing (e.g., JSON.stringify(parsedObject)) can change key ordering, whitespace, or Unicode escaping, causing signature mismatches.

Implementation Examples

The examples below verify the default HMAC-SHA256 algorithm and process payment notifications only. For HMAC-SHA512, use SHA-512 and the hmac_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:
  1. Check timestamp: Reject webhooks with timestamps older than 5 minutes (already shown in verification examples above)
  2. Store webhook IDs: Save the envelope event id and acknowledge duplicates without applying them again. This prevents replayed webhooks within the timestamp window
  3. 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 event id 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:
The HTTP request sent to your endpoint uses the same body envelope as automatic webhook delivery:
Test deliveries include the production-style signature headers: 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 a webhook_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

  1. Include webhook_url in your POST /payments request
  2. Choose notification types with the optional webhook_events array
  3. Receive signed notifications at the specified URL and verify them with the signing secret issued for your merchant

Example

Default Events

If webhook_events is not provided, the following events are subscribed by default:
  • payment.created
  • payment.completed
  • payment.failed
  • payment.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 event id 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 envelope id 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.