Webhooks

HMAC-signed payment events pushed to your server

Add an endpoint

Dashboard → Webhooks → add your HTTPS URL and choose events (start with payment.confirmed). You’ll get a signing secret (whsec_…).

Payload

POST https://yourserver.com/webhooks/puffin
X-Puffin-Signature: 3f5a…   // HMAC-SHA256 of the raw body

{
  "event": "payment.confirmed",
  "data": {
    "paymentIntentId": "9b1f…",
    "amount": "25.00",
    "token": "USDC_SOL",
    "txHash": "5j8K…"
  },
  "timestamp": "2026-07-04T12:00:00.000Z"
}

Verify the signature

Always verify before trusting anything:

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(rawBody, signature, secret) {
  const expected = createHmac('sha256', secret).update(rawBody).digest('hex');
  return expected.length === signature.length &&
    timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Events

Event	Fires when
payment.confirmed / payment.confirmed_late	A payment intent’s received amount covers its target
payment.dispute_opened	A payer reports sending funds that didn’t match an intent
payment.late_returned / payment.late_recovery_queued / payment.late_expired	Late-payment handling per your latePaymentPolicy
wallet.deposit.detected / wallet.deposit.confirmed	A deposit lands on a WaaS wallet you created via the API — distinct from the payment-intent flow above
bridge.completed / bridge.failed	A bridge transfer reaches a terminal state

wallet.* and bridge.* payloads include walletId/bridgeTransferId, chain/route, amount, and the relevant transaction hash(es) — shaped the same way as their API responses in Wallets and Bridge.

Disputes

A dispute is opened when a customer, from your checkout page, reports sending funds that didn’t automatically confirm — wrong amount, wrong address, or a late send. It’s self-service on the customer’s side (they get an instant matchedWallet / amountCovered / lateByMinutes result), and payment.dispute_opened gives you the same detail so you can follow up manually if the automated check doesn’t resolve it — for example, crediting an order despite a slightly-underpaid amount, at your discretion.

Delivery & retries

• Respond 2xx within 10 seconds; anything else counts as a failure.
• We retry up to 3 times with backoff; deliveries and status codes are visible in the dashboard.
• Handlers must be idempotent — key on paymentIntentId.