Webhooks - Onflay Docs

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.

Signed webhooks (X-Onflay-Signature) are the authenticity control. Stable egress identity is not part of this contract; see docs/engineering/commerce-safety-contract.md (Developer Webhook Network Identity). In sandbox, POST /v1/cli/trigger persists a fixture delivery through the worker.

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.