Integrate XPay webhooks

Receive and verify asynchronous XPay notifications for payments, payment tokens, subscriptions, and invoices. Configure one secure endpoint, then let resource-specific guides define the events and merchant actions for their domain.

Configure the endpoint#

1. Sign in to the XPay Admin Panel.
2. Open Store Info.
3. Open Keys Details.
4. Locate the webhook configuration.
5. Add the merchant's public HTTPS endpoint.
6. Save the configuration.
7. Copy the Webhook HMAC secret and store it on the merchant backend.

The endpoint must be reachable by XPay over HTTPS. Do not place browser-user authentication in front of it.

Verify the signature#

XPay sends the signature in x-signature. Generate the expected HMAC SHA-256 digest from JSON.stringify(payload) using the Webhook HMAC secret.

const crypto = require("crypto");

function verifyXPayWebhook(payload, receivedSignature, webhookSecret) {
  const expectedSignature = crypto
    .createHmac("sha256", webhookSecret)
    .update(JSON.stringify(payload))
    .digest("hex");

  const received = Buffer.from(receivedSignature, "utf8");
  const expected = Buffer.from(expectedSignature, "utf8");

  return (
    received.length === expected.length &&
    crypto.timingSafeEqual(received, expected)
  );
}

For each request:

1. Read the JSON payload and the x-signature header.
2. Generate the expected signature from JSON.stringify(payload).
3. Compare the signatures with a timing-safe operation.
4. Reject the request when verification fails.
5. Process the event only after verification succeeds.

Process the notification#

• Store the event identifier when XPay provides one.
• Prevent a repeated notification from repeating the same business action.
• Correlate the event through its PaymentIntent, subscription, invoice, or refund identifiers.
• Retrieve the current XPay resource before making a permanent decision after an ambiguous or apparently stale notification.
• Return a successful HTTP response after the event has been accepted for processing.
• Keep credentials, signatures, and reusable payment tokens out of logs.

Retry timing and event-order guarantees are not defined in this guide.

Receive a payment token#

For a PaymentIntent created with metadata.reason set to token:

1. Verify the webhook.
2. Match its PaymentIntent ID to the merchant token request.
3. Confirm the successful tokenization result.
4. Read the payment token ID from token.id.
5. Associate the token with the correct customer record.

The token is delivered through the webhook, not through the confirmPayment() result.

Next steps#

• Payment webhook events.
• Collect a payment token with XPay Element.
• See the XPay API reference for canonical payload schemas.
• Use the resource-specific webhook guide for public event names and merchant actions.