📘

The API:

• Signs all webhooks (for both Embedded and Hosted Checkout) with a signature using the secret token as the key.
• Sends all webhooks from a known range of IP addresses.

📘

In certain circumstances, Peach Payments could update a checkout status using webhooks after a checkout session ends. For example, system issues might result in a checkout status being incorrect during the session; when the session ends and the system recovers, Peach Payments sends a webhook with the updated status.

Transaction statuses can change as follows:

• Created -> Pending
• Pending -> Successful, cancelled, or uncertain
• Uncertain or cancelled -> Successful

Peach Payments cannot guarantee the order of webhooks. For example, if your customer initiates a transaction and Peach Payments sends a pending webhook but you have a system issue that causes the webhook to go into exponential backoff, Peach Payments might send the next webhook before the pending webhook gets retried. The webhook payload contains a timestamp that you can use to identify the correct order of webhooks.

You can secure your webhook endpoints using HMAC SHA256 signing. When you enable webhook signing, Peach Payments signs each webhook payload so that you can verify that a request genuinely comes from Peach Payments and that no one has tampered with it in transit.

Enable webhook signing

📘

Only certain roles can enable webhook signing.

You can enable webhook signing from the Peach Payments Dashboard:

1. Log in to your Peach Payments Dashboard and configure a webhook.
2. Under Webhook security, click the Enable webhook signing toggle to the on position.
3. In the Enable webhook signing window, copy the shared secret key that Peach Payments uses to sign your webhooks, then click Enable.

You can view and copy the secret key again at any time under Webhook security. You need this key to verify webhook signatures.

After you enable webhook signing, you can:

• Disable webhook signing. Click the Enable webhook signing toggle to the off position, then click Disable. Peach Payments stops signing your webhook payloads.
• Regenerate the secret key. Under Webhook security, click Regenerate secret key. Update your integration with the new key, because Peach Payments signs webhooks with the new key immediately.

If you disable and later re-enable signing without regenerating the key, Peach Payments uses your existing configured secret key.

Verify webhook signatures

After you enable webhook signing, each webhook request includes x-webhook-signature-algorithm, x-webhook-timestamp, x-webhook-id, and x-webhook-signature headers. You must verify the authenticity of the request by recalculating the signature using your secret key and comparing it to the value that Peach Payments sends.

When you recalculate the signature:

• Use the raw request body exactly as you receive it. Checkout sends the body as form-urlencoded data, whereas Payment Links sends it as JSON.
• Ensure that the URL matches the webhook URL that you configured on the Peach Payments Dashboard.

Peach Payments includes the webhook ID in the signature message to:

• Prevent replay attacks by tying the signature to a specific webhook instance.
• Enable correlation between merchant logs and Peach Payments logs for troubleshooting.
• Allow merchants to verify the integrity of the webhook ID for idempotency checking.

The following code snippet shows how to verify the HMAC signature in Node (remember to replace placeholder values with your own values):

const crypto = require('crypto');

const timestamp = get('request.header.x-webhook-timestamp');
const webhookId = get('request.header.x-webhook-id');
const receivedSignature = get('request.header.x-webhook-signature');
const url = get('request.url'); // Must match your configured webhook URL
const payload = get('request.content'); // Raw body: form-urlencoded for Checkout, JSON for Payment Links

const secret = 'some-secret'; // Must match Peach Payments secret

const message = `${timestamp}.${webhookId}.${url}.${payload}`

const calculatedSignature = crypto
  .createHmac('sha256', secret)
  .update(message)
  .digest('hex');

const isValid = calculatedSignature === receivedSignature;

if (isValid) {
  console.log('✅ HMAC Signature Valid');
  console.log(`Timestamp: ${timestamp} (${new Date(timestamp * 1000).toISOString()})`);
  console.log(`Webhook ID: ${webhookId}`);
  console.log(`Signature: ${calculatedSignature.substring(0, 16)}...${calculatedSignature.substring(48)}`);
} else {
  console.log('❌ HMAC Signature Invalid');
  console.log(`Expected: ${calculatedSignature}`);
  console.log(`Received: ${receivedSignature}`);
  console.log(`Message: ${message.substring(0, 100)}...`);
}

set('hmac_valid', isValid);
set('hmac_signature', calculatedSignature);

Peach Payments expects a 200 HTTP for successful webhook delivery and a non-200 HTTP status code for failures.

For an unsuccessful response, Peach Payments retries the webhook for 30 days or until a successful acknowledgement (200 HTTP) occurs.

Exponential backoff retry

Below is the exponential backoff logic.

The interval between retries is:

• 2 minutes
• 4 minutes
• 8 minutes
• 15 minutes
• 30 minutes
• 1 hour, every day until 30 days have passed since the first attempt