Verify webhooks

Install the SDK for your frameworkCopy Anchor Link

# Next.js
pnpm add @fianto/nextjs @fianto/sdk
# Express
pnpm add @fianto/express @fianto/sdk
# Hono
pnpm add @fianto/hono @fianto/sdk

Add the webhook routeCopy Anchor Link

The handler reads the raw body itself, checks the signature and the timestamp, answers endpoint.verification, and calls the callback for the event's type. Wire onVerificationError and onError: a wrong or missing secret fails exactly like a forged request, and the response never says why.

// app/api/webhooks/fianto/route.ts
import { Webhooks } from '@fianto/nextjs';

export const POST = Webhooks({
  secret: process.env.FIANTO_WEBHOOK_SECRET,
  onOrderPaid: async (event) => {
    // Record event.id in the same database transaction as the fulfilment,
    // and skip ids you have already seen.
    console.log('paid', event.data.order_id, event.id);
  },
  onSubscriptionEnded: async (event) => {
    console.log('ended', event.data.id, event.data.end_reason);
  },
  onVerificationError: (error) => console.warn('fianto webhook rejected:', error.reason),
  onError: (error, event) => console.error('fianto webhook failed:', event.id, error),
});

What the handler answers:

There is one callback per event type (onCheckoutSessionCompleted … onTestEvent), plus onEvent, which runs after the type's own callback for every verified event except the verification challenge.

Or verify by hand with verifyWebhookCopy Anchor Link

verifyWebhook(rawBody, headers, { secret }) checks the signature and returns the parsed event. Pass the body exactly as received, as a string, Uint8Array or ArrayBuffer, never re-serialised JSON. Your route then answers endpoint.verification itself.

// app/api/webhooks/fianto/route.ts
import { isWebhookVerificationError, verifyWebhook } from '@fianto/sdk/webhooks';

export async function POST(request: Request) {
  const body = await request.arrayBuffer(); // the raw bytes, never request.json()
  let event;
  try {
    event = await verifyWebhook(body, request.headers, { secret: process.env.FIANTO_WEBHOOK_SECRET });
  } catch (error) {
    if (isWebhookVerificationError(error)) {
      console.warn('fianto webhook rejected:', error.reason);
      return Response.json({ error: 'invalid_webhook' }, { status: 400 });
    }
    throw error;
  }

  switch (event.type) {
    case 'endpoint.verification':
      return Response.json({ challenge: event.data.challenge });
    case 'order.paid':
      console.log('paid', event.data.order_id, event.id);
      break;
    default:
      break; // answer 2xx for types you do not handle, including newer ones
  }
  return Response.json({ received: true });
}

verifyWebhook throws a WebhookVerificationError whose reason is one of:

toleranceSeconds can be set from 1 to 3,600; it cannot be switched off.

Keep your clock in syncCopy Anchor Link

The timestamp check compares webhook-timestamp with your server's clock. fianto signs every attempt when it sends it, so retries hours later still pass. A server clock more than 300 seconds off rejects every delivery with timestamp_out_of_tolerance. Run NTP or your platform's time sync.

Roll the signing secret without dropping deliveriesCopy Anchor Link

1. In the application's webhook settings, choose Roll signing secret. Pick when the current secret stops working: "Immediately", "In 1 hour" (the default) or "In 24 hours". The roll asks for your password (and 2FA code) and shows the new secret.
2. Until the old secret stops working, every delivery carries two signatures, one per secret, so a route holding either secret verifies it.
3. Put the new secret in your server's environment before the old one stops working. While you switch over, you can give the handler both secrets; a delivery verifies when any of them matches.

// app/api/webhooks/fianto/route.ts
import { Webhooks } from '@fianto/nextjs';

// Drop whichever variable is not set (before the switch, or after the old one is retired).
const secrets = [process.env.FIANTO_WEBHOOK_SECRET, process.env.FIANTO_WEBHOOK_SECRET_OLD].filter(
  (secret): secret is string => Boolean(secret),
);

export const POST = Webhooks({
  // An empty array throws when the route is set up; undefined falls back to FIANTO_WEBHOOK_SECRET.
  secret: secrets.length ? secrets : undefined,
  onOrderPaid: async (event) => {
    console.log('paid', event.data.order_id, event.id);
  },
});

verifyWebhook takes the same array as its secret. At most two secrets are valid at once: a new roll ends any older secret's grace period at once.