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

> ## Agent Instructions
> Documentação oficial da sinnu, gateway de pagamento brasileiro: Pix e cartão de crédito. O índice de todas as páginas está em https://docs.sinnu.com.br/llms.txt.
> A API (https://api.sinnu.com.br) e o checkout (https://pay.sinnu.com.br) documentados são de produção. Não há ambiente público de testes: cada chamada cria ou altera dados reais.
> A chave secreta sk_live_ fica só no servidor. O navegador recebe apenas o slug do link ou a URL do checkout.
> Unidades: amountCents do link e os valores de /api/transactions/ estão em centavos (inteiro). data.amount do webhook e amount das transações de um link estão em reais. Compare na mesma unidade.
> Status: a API de transações usa approved; o corpo do webhook usa paid; o evento é transaction.approved.
> Libere o pedido só pelo webhook assinado (X-Sinnu-Signature, validado sobre o corpo cru com constructEvent({ payload, signature, secret })) e confirme com transactions.get. Nunca pelo evento completed do Sinnu Elements nem pelos parâmetros da URL de retorno.
> Estorno é sempre do valor total. Não invente métodos, campos ou eventos: confira na referência do SDK e da API.

# Valide webhooks com o SDK

> Receba o corpo original, confira a assinatura e persista o evento antes de responder.

`constructEvent` verifica a assinatura e interpreta o JSON. A função usa `node:crypto` e não faz chamadas à API.

| Helper | Resultado |
| - | - |
| `constructEvent(options)` | Evento interpretado; lança `SinnuWebhookSignatureError` em falhas de assinatura ou JSON. |
| `verifySignature(options)` | Booleano para a comparação; assinatura ausente ou segredo vazio lançam erro. |
| `computeSignature(payload, secret)` | HMAC hexadecimal; útil para testes locais. |

## Handler de referência

O handler abaixo recebe duas dependências: o segredo e uma função `persist` que grava em banco ou fila durável. O exemplo só confirma entregas após essa gravação. A implementação de persistência pertence à sua aplicação.

```ts webhook.ts theme={null}
import {
  constructEvent,
  SinnuWebhookSignatureError,
  type SinnuWebhookEvent,
} from "@sinnu-dev/sdk";

type SaveEventDurably = (event: SinnuWebhookEvent) => Promise<void>;

function isValidEvent(event: SinnuWebhookEvent | null): event is SinnuWebhookEvent {
  return (
    !!event &&
    event.version === "1" &&
    typeof event.type === "string" &&
    !!event.data &&
    typeof event.data === "object" &&
    !Array.isArray(event.data)
  );
}

export function createWebhookHandler(secret: string, saveDurably: SaveEventDurably) {
  if (!secret) throw new Error("Configure SINNU_WEBHOOK_SECRET.");

  return async function POST(request: Request): Promise<Response> {
    let event: SinnuWebhookEvent;
    try {
      event = constructEvent({
        payload: await request.text(),
        signature: request.headers.get("X-Sinnu-Signature") ?? undefined,
        secret,
      });
    } catch (error) {
      const reason = error instanceof SinnuWebhookSignatureError ? "Assinatura inválida" : "Não foi possível ler o evento";
      return new Response(reason, { status: 400 });
    }

    if (!isValidEvent(event)) return new Response("Evento inválido", { status: 400 });
    if (event.test === true) return new Response(null, { status: 204 });

    try {
      await saveDurably(event);
      return new Response(null, { status: 204 });
    } catch {
      return new Response("Tente novamente", { status: 503 });
    }
  };
}
```

## Use com Next.js

Exporte o handler como `POST` no arquivo `app/api/webhooks/sinnu/route.ts`. Declare `export const runtime = "nodejs"` e conecte sua persistência. Não use `request.json()` antes de verificar a assinatura.

## Verifique também o conteúdo

O parâmetro genérico de `constructEvent<T>` informa tipos ao TypeScript, mas não valida `T` em runtime. Confira os campos usados pela sua aplicação antes de processar.

O worker deve consultar a transação, conferir o pedido e impedir liberação duplicada. Veja a [receita de conciliação](https://docs.sinnu.com.br/guias/conciliacao.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.