Webhooks

Webhooks let the payment provider (x402) notify you asynchronously when a payment changes state (confirmed, failed, refunded). They are critical for final reconciliation — do not rely only on immediate HTTP responses.

Typical webhook events

payment.confirmed — payment finalized on-chain or off-chain
payment.failed — processing or on-chain failure
payment.refunded — refund processed

Security: verify the webhook

Always verify webhook authenticity. x402 likely provides either:

an X-Provider-Signature header (HMAC), or
a signing key + signature you verify with public key cryptography.

Example HMAC verification (Node):

import crypto from 'crypto';

function verifyWebhook(req, secret) {
  const raw = JSON.stringify(req.body);
  const sig = req.headers['x-x402-signature'];
  const expected = crypto.createHmac('sha256', secret).update(raw).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}