> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onflay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Recibe eventos firmados de Onflay de forma segura.

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

## Instalar

```bash theme={"dark"}
pnpm add @onflay/webhooks
```

## Next.js App Router

```ts theme={"dark"}
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

```ts theme={"dark"}
import { verifyWebhookSignature } from '@onflay/webhooks';

const { event } = verifyWebhookSignature(
  rawBodyString,
  request.headers.get('x-onflay-signature'),
  { secret: process.env.ONFLAY_WEBHOOK_SECRET! }
);
```

<Warning>
  La verificación requiere el body crudo. Si parseas y vuelves a serializar el JSON, la firma no va a coincidir.
</Warning>

## 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`.