Webhook Handling - SolvaPay Documentation

For the complete webhook guide — setup, signature verification, event catalog, payload schemas, and best practices — see the central Webhooks documentation.

Quick Reference

import { verifyWebhook } from '@solvapay/server'

const event = verifyWebhook({
  body: rawBodyString,
  signature: request.headers.get('sv-signature')!,
  secret: process.env.SOLVAPAY_WEBHOOK_SECRET!,
})

switch (event.type) {
  case 'payment.succeeded':
    // fulfil the order
    break
  case 'purchase.created':
    // grant access
    break
  case 'purchase.cancelled':
    // revoke access
    break
}

Edge Runtimes

import { verifyWebhook } from '@solvapay/server/edge'

const event = await verifyWebhook({
  body: rawBodyString,
  signature: svSignatureHeader,
  secret: process.env.SOLVAPAY_WEBHOOK_SECRET!,
})

Fetch runtimes (Deno, Cloudflare Workers, Supabase Edge)

For web-standards fetch runtimes, @solvapay/server/fetch provides a solvapayWebhook factory that handles the full lifecycle (read body, verify signature, parse, respond):

// supabase/functions/solvapay-webhook/index.ts
import { solvapayWebhook } from '@solvapay/server/fetch'

Deno.serve(solvapayWebhook({
  onEvent: async event => {
    // Handle events here
  },
}))

The factory reads SOLVAPAY_WEBHOOK_SECRET from the environment automatically. Use verifyWebhook from @solvapay/server/edge if you need manual control over the request lifecycle. See the Supabase Edge Functions guide for the complete setup.

Event Types

SolvaPay emits 46 event types across these domains. event.type is fully typed as WebhookEventType, so your editor autocompletes every name and narrows event.data.object in a switch.

Domain	Examples
Customer	`customer.created`, `customer.updated`, `customer.deleted`
Purchase & subscription	`purchase.created`, `purchase.activated`, `purchase.renewed`, `purchase.past_due`, `purchase.cancellation_scheduled`, `purchase.cancelled`, `purchase.plan_changed`, `purchase.refunded`
Payments, refunds & disputes	`payment.succeeded`, `payment.failed`, `payment.refunded`, `payment.refund_pending`, `payment.canceled`, `payment.disputed`, `payment.dispute_closed`
Payouts	`payout.paid`, `payout.failed`
Checkout	`checkout_session.created`, `checkout_session.completed`, `checkout_session.expired`
Credits	`customer.credit.topped_up`, `customer.credit.debited`, `customer.credit.low_balance`, `customer.credit.exhausted`, `customer.credit.granted`, `customer.credit.adjusted`, `customer.credit.auto_topup_failed`
Usage & metering	`usage.charged`, `usage.recorded`, `usage.reset`
Catalog	`product.created/updated/archived`, `plan.created/updated/archived`

See the central Webhooks documentation for the full table and per-event payload schemas.

Subscribing to specific events

Endpoints receive all events by default. To receive only a subset, set enabledEvents when creating/updating the endpoint (empty = all), or choose Selected events in the Console. See Choosing which events to receive.

Side effects on Customer and Transaction records

Two SolvaPay-internal webhook handlers update derived data you may rely on:

Card mirror on payment_intent.succeeded. When a payment succeeds, SolvaPay mirrors the card brand, last4, expMonth, and expYear onto the Customer record. GET /v1/sdk/payment-method?customerRef=… reads from this mirror, so the SDK’s usePaymentMethod hook and CurrentPlanCard never round-trip to Stripe. The mirror is updated whenever a new successful payment lands, so the “payment method on file” always reflects the last working card.
Refund FX normalization. For refunds against transactions with a non-unity exchange rate (e.g. EUR → USD), the refund record now stores both the original-currency amount and the USD equivalent computed from the source transaction’s stored exchangeRate. This keeps credit balances and revenue reports consistent after cross-currency refunds.

Both behaviors are idempotent and safe to replay. See Webhooks documentation for full payload schemas and integration examples.

​Quick Reference

​Edge Runtimes

​Fetch runtimes (Deno, Cloudflare Workers, Supabase Edge)

​Event Types

​Subscribing to specific events

​Side effects on Customer and Transaction records