Guide

Webhooks

Use webhooks to reconcile final payment state on your backend. Webhook processing should verify signatures, persist the raw event, and update local order state idempotently.

Inspect webhook endpoints Review failure handling

Webhook handling model

Custom API webhooks are not the WooCommerce plugin webhook. For a custom REST integration, you expose and configure your own HTTPS callback URL; Foxpay sends signed payment-status events to that URL. WooCommerce uses plugin-specific callback routes and should not be reused for custom integrations.

Verify the request signature before mutating application state.
Persist the raw payload and relevant identifiers before acknowledging receipt.
Process deliveries idempotently using the event or payment identifier as a deduplication key.
Use webhook reconciliation as the authoritative backend state transition for your order lifecycle.
Use polling for buyer-facing progress and webhook delivery for durable backend completion handling.

Panel configuration

For custom REST integrations, configure the merchant webhook URL in the Custom Integration settings for the store.

The configured URL is stored as the custom webhook target for that store.
Outbound custom webhooks must be enabled for Foxpay to deliver status changes to that URL.
The same store-level Foxpay webhook secret is used to sign custom webhook deliveries.
The webhook URL should point to the merchant backend, not to a WooCommerce plugin callback route.

Verification example

import crypto from 'node:crypto';

function verifyFoxpaySignature(rawBody, receivedSignature, secret) {
  const signature = receivedSignature.replace(/^sha256=/, '');
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  if (signature.length !== expected.length) {
    return false;
  }

  return crypto.timingSafeEqual(
    Buffer.from(expected, 'utf8'),
    Buffer.from(signature, 'utf8')
  );
}

Custom API delivery

Foxpay sends `POST` requests to your configured custom webhook URL.
Each delivery includes `X-Foxpay-Signature`, `X-Foxpay-Event`, `X-Foxpay-Delivery`, and `User-Agent: Foxpay-Webhooks/1.0`.
The default payment event is `transaction.status_changed`.
The JSON payload includes `event`, `transaction_id`, `order_id`, `status`, `amount`, `currency`, `timestamp`, and optional `metadata`.
For custom API transactions, treat monetary amounts as integer cents.
The signature header format is `X-Foxpay-Signature: sha256=<hex>`, generated with HMAC-SHA256 over the exact JSON request body.

Verification handshake

When outbound webhooks are enabled, Foxpay can verify your callback by sending a signed `foxpay.webhook_verification` event. Your endpoint should verify the signature and respond with JSON that echoes the received `challenge` and confirms successful verification.

{
  "challenge": "received-challenge-value",
  "signatureValid": true
}

Delivery semantics

Treat webhook delivery as at-least-once.
Handle duplicate delivery idempotently.
Acknowledge quickly after durable persistence.
Retain enough payload and signature context to investigate disputes, delivery retries, or operational incidents.

Operational guidance

Record `paymentId`, `orderId`, `merchantId`, and the received event identifier for each delivery.
Separate validation failures from downstream business-logic failures in your logs and alerting.
Retry internal processing safely when your own downstream systems are transiently unavailable.
Contact support with relevant identifiers when webhook behavior differs from the published contract.