# Guia de webhooks

Confirmações automáticas, eventos e assinatura HMAC.

## Cadastrar um endpoint

Informe um domínio HTTPS público e selecione os eventos necessários. O segredo aparece uma vez na criação. [Cadastrar webhook](/docs/api-reference/endpoint/webhooks/create).

```
{
  "url": "https://seu-dominio.com/webhook",
  "events": [
    "payment.paid",
    "withdrawal.completed"
  ]
}
```

## Eventos disponíveis

EventoQuando é usado

`payment.created`Cobrança criada

`payment.paid`Confirmação de pagamento

`payment.failed`Operação não concluída

`payment.refunded`Devolução concluída

`pix.received`Confirmação de pagamento

`pix.sent`Resultado de um envio

`transaction.paid`Confirmação de pagamento

`withdrawal.completed`Resultado de um envio

`withdrawal.failed`Operação não concluída

## Validar a assinatura

Calcule HMAC-SHA256 sobre os bytes originais do corpo, usando o segredo do endpoint. Compare com o valor do header `X-Webhook-Signature`, após remover `sha256=`.

```
import { createHmac, timingSafeEqual } from 'node:crypto';

const expected = createHmac('sha256', process.env.WEBHOOK_SECRET)
  .update(rawBody).digest('hex');
const supplied = signature.replace(/^sha256=/, '');
const valid = supplied.length === expected.length &&
  timingSafeEqual(Buffer.from(supplied), Buffer.from(expected));
```

## Formato do evento

```
{
  "id": "pay_exemplo:payment.paid",
  "event": "payment.paid",
  "data": {
    "id": "pay_exemplo",
    "amount": 5,
    "feeAmount": 0.1,
    "netAmount": 4.9,
    "status": "COMPLETED",
    "currency": "BRL"
  },
  "createdAt": "2026-11-10T15:00:00.000Z"
}
```

## Confirmação e retentativas

Responda HTTP 2xx após validar e registrar o evento. Deduplique pelo `id`. As entregas têm timeout de 8 segundos, até cinco tentativas e intervalos crescentes de 30, 60, 120 e 240 segundos. O envio automático depende da fila e do transporte de webhooks ativos no ambiente.
