XPayr Webhook Examples

Secure webhook verification examples for XPayr, including raw-body HMAC validation, idempotency, retries, and durable processing patterns.

Status: Public reference implementation

Purpose

Help backend teams process XPayr events safely across common server runtimes.

Included

• Node.js, PHP, and Python verification examples
• Shared deterministic signature fixtures
• Idempotent event-processing guidance

Quick start

npm install
npm test

Processing contract

1. Read the HTTP request body as untouched bytes. Do not parse or re-serialize it first.
2. Verify X-XPayr-Signature with HMAC-SHA256 and your webhook secret.
3. Require a stable event ID and enforce uniqueness in durable storage.
4. Persist the event and the payment-state transition in one transaction.
5. Return 2xx only after durable processing; retries must produce the same result.

Runnable handlers are available under node/, php/, and python/. The shared fixture ensures all runtimes implement the same signature contract.

Use an XPayr test key before live credentials. Never expose sk_test_*, sk_live_*, agent keys, webhook secrets, or wallet private keys in browser code or commits.

Documentation

• Developer Hub
• Merchant API documentation
• Testnet checkout guide
• Webhook signature guide

Security

Read SECURITY.md before reporting a vulnerability. Payment completion must be based on verified XPayr webhook/API state and canonical on-chain evidence, not browser callbacks alone.

License

MIT. See LICENSE.