Webhooks

Receive real-time notifications when payment events occur. All webhooks are signed with HMAC-SHA256 for security.

Event Types

Event	Description
payment.created	Payment intent created
payment.authorized	Payment authorized by rail provider
payment.settled	Funds successfully transferred
payment.failed	Payment failed (NSF, rejected, etc.)
payment.refunded	Refund processed

Webhook Payload

{
  "id": "evt_abc123",
  "type": "payment.settled",
  "created_at": "2026-02-18T20:00:00Z",
  "data": {
    "id": "pay_def456",
    "status": "settled",
    "amount": 10000,
    "currency": "USD",
    "rail_selected": "rtp"
  }
}

Signature Verification

Verify webhook signatures using your webhook secret and the X-FetcherPay-Signature header.

// Node.js example
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}