Architecture Best Practices

Event-Driven Webhooks vs. Periodic Status Polling

Why modern Web3 commerce stacks use HMAC SHA-256 signed webhooks for instant crypto settlement instead of continuous API polling.

Direct Comparison Matrix

Criterion REST API Polling (GET /status) XPayr Webhook (POST Event)
Latency / Fulfillment Speed Delayed by interval (e.g. 5-30 seconds) Instant (< 250ms on blockchain confirmation)
Server Load & Ingress Bandwidth High: Hundreds of redundant GET requests per order Minimal: Exactly 1 POST request on state change
Rate Limit Vulnerability Prone to 429 Too Many Requests during traffic spikes Zero: Inbound push model bypasses rate limits
Signature & Security Proof API Token Bearer Authentication HMAC-SHA256 Payload Hash Verification

Recommended Hybrid Pattern for Enterprise E-Commerce

For mission-critical production systems, we recommend using Webhooks as Primary and Polling as Fallback:

  1. Primary (Instant): Listen for the payment.confirmed signed webhook to fulfill digital downloads, API keys, or physical shipments instantly.
  2. Safety Net: Run a reconciliation background job every 30 minutes that queries GET /api/v1/payments/{id}/status only for orders older than 15 minutes that haven't received a webhook ack.
View Webhook Verification Guide → Interactive Webhook Tester Test Status Tool in MCP Playground Open OpenAPI Specification
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