Webhook Validation

Webhook Signature Verification

When you set webhookUrl while creating a payment link, SX Digital Pay signs every webhook request (payment_link.created, payment_link.status_changed, payment_link.payment_status_changed).

Headers:

x-sxpay-signature: HMAC-SHA256 hex digest of "{timestamp}.{rawBody}" using the link’s webhookSecret.

x-sxpay-timestamp: Epoch milliseconds (use to prevent replay).

Verification steps:

Read the raw request body (exact bytes, before JSON parse).

Compute expected = HMAC_SHA256(webhookSecret, timestamp + "." + rawBody).

Compare expected with x-sxpay-signature using constant-time comparison.

Optionally reject if the timestamp is too old (e.g., > 5 minutes) to mitigate replay attacks.

Node.js Example

Handling Failures

If verification fails, return a non-2xx status; SX Digital Pay will treat the delivery as failed.

Make sure your endpoint responds quickly (ideally < 5s) and is highly available; retries from SX Digital Pay will occur when the response is non-2xx.

Best Practices

Store webhookSecret securely; it is only returned at link creation time.

Use HTTPS for webhookUrl.

Log request IDs and timestamps to help debug delivery issues.

Rotate API keys and webhook endpoints/secrets when decommissioning environments.

Webhook Signature Verification#

Node.js Example#

Handling Failures#

Best Practices#

Webhook Signature Verification

Node.js Example

Handling Failures

Best Practices