Webhook trust

Verify the event before you update the order.

XPayr signs webhook payloads with your webhook secret. Store the raw request body, verify X-XPayr-Signature, then process the event idempotently.

Headers to read

  • X-XPayr-Signature: HMAC SHA-256 signature prefixed with sha256=.
  • X-XPayr-Event: event type such as payment.completed.
  • X-XPayr-Delivery: delivery/event identifier where available.

Multi-Language Verification Snippets

import crypto from "node:crypto";

export function verifyXPayrWebhook(rawBody, signatureHeader, secret) {
  const received = String(signatureHeader || "").replace(/^sha256=/, "");
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(received, "hex"),
    Buffer.from(expected, "hex")
  );
}

Events to handle

At minimum, handle payment.completed, payment.failed, payment.expired, test.webhook. Use the session ID and your own metadata order ID to reconcile.

Official NPM SDKs (v0.2.0) & Remote MCP Server

Integrate Faster with Official XPayr Packages & Zero-Install MCP

Install @xpayr/node-sdk (v0.2.0), @xpayr/payment-evidence (v0.2.0), @xpayr/extension-kit (v0.2.0), or @xpayr/mcp-server (v1.0.0) from NPM, or execute live JSON-RPC 2.0 tool calls via POST https://xpayr.com/api/mcp.

Live MCP Playground (/tools/mcp-playground) ES256 License Verifier AI Agent Policy Simulator HMAC-SHA256 Webhook Tester mcp.xpayr.com docs.xpayr.com api-docs.xpayr.com