Saltar al contenido principal
Los webhooks te permiten reaccionar a eventos como pagos completados, reembolsos, payouts y disputas.

​
Instalar

pnpm add @onflay/webhooks

​
Next.js App Router

import { createNextWebhookHandler } from '@onflay/webhooks/next';

export const POST = createNextWebhookHandler({
  secret: process.env.ONFLAY_WEBHOOK_SECRET!,
  onEvent: async (event) => {
    switch (event.type) {
      case 'payment.completed':
        // Activa acceso o marca la orden como pagada.
        break;
      case 'payment.refunded':
        // Ajusta acceso o balance interno.
        break;
      default:
        break;
    }
  },
});

​
Verificación manual

import { verifyWebhookSignature } from '@onflay/webhooks';

const { event } = verifyWebhookSignature(
  rawBodyString,
  request.headers.get('x-onflay-signature'),
  { secret: process.env.ONFLAY_WEBHOOK_SECRET! }
);
La verificación requiere el body crudo. Si parseas y vuelves a serializar el JSON, la firma no va a coincidir.

​
Buenas prácticas

  • responde rápido con 2xx;
  • procesa trabajo pesado en una cola;
  • guarda event.id para evitar duplicados;
  • usa secrets distintos para sandbox y producción;
  • no actives acceso solo por successUrl.