Provider webhooks

Current webhook scope

The documented endpoint is an inbound webhook from a payment provider to LuxPay. It is not a general merchant subscription endpoint that sends LuxPay events to every merchant. Only authorized provider partners use this route. Merchant outbound webhooks require a separate contract when such a surface is provisioned.

Headers

Send X-Signature and X-Timestamp. Prefer a stable event identifier in X-Provider-Event-Id. The server can inspect several alternate headers and common payload fields, but the dedicated header provides the least ambiguous deduplication contract.

Signature and replay protection

Sign the original payload using the method agreed with LuxPay. Do not reorder or re-encode JSON after signing. The server verifies signature and timestamp to reject replay. A failed verification returns 403. An accepted event returns status accepted and is queued for processing.

Duplicates

LuxPay deduplicates by provider and provider event identifier. A 200 response with duplicate: true is a successful delivery result, not a request to send a new event. Reuse the same event identifier across every delivery attempt.

Sensitive data

Do not include a password, secret, or access token in the event payload. LuxPay masks sensitive-looking fields in its receipt log, but masking is not a substitute for data minimization. Use HTTPS, a short timeout, and bounded retry with backoff.