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

# Webhooks

> Receba avisos automáticos quando um pagamento é confirmado, um reembolso acontece ou um saque é concluído.

Quando algo acontece na sua loja, a BukioPay faz um `POST` na URL que você cadastrou, com o corpo assinado.

Cadastre a URL e marque os eventos desejados nas configurações de API do painel. **Um evento só é entregue se estiver marcado** — sem seleção, nada é enviado.

## Envelope

Todo evento chega no mesmo formato:

```json theme={null}
{
  "event": "payment.paid",
  "data": { },
  "requestId": "req_0123456789abcdef",
  "createdAt": "2026-08-26T12:00:00.000Z"
}
```

## Headers

| Header | Conteúdo |
| - | - |
| `X-Webhook-Event` | Nome do evento, igual ao campo `event` |
| `X-Webhook-Id` | Mesmo valor de `requestId`, use para deduplicar |
| `X-Webhook-Signature` | Assinatura HMAC, veja [Validar a assinatura](/api-reference/webhooks/assinatura) |
| `User-Agent` | `BukioPay-Webhooks/1.0` |

## O que esperamos do seu endpoint

<AccordionGroup>
  <Accordion title="Responder 2xx rapidamente">
    O tempo limite é de 15 segundos. Se o processamento for demorado, enfileire e responda antes.
  </Accordion>

  <Accordion title="Ser idempotente">
    Use `requestId` como chave. Um reenvio pelo painel preserva o mesmo `requestId`, então a mesma entrega não deve ser processada duas vezes.
  </Accordion>

  <Accordion title="Aceitar apenas HTTPS público">
    Destinos em localhost ou em redes privadas são recusados, e redirecionamentos não são seguidos.
  </Accordion>
</AccordionGroup>

<Warning>
  Nunca considere um pagamento aprovado por informação vinda do frontend. Confie no webhook assinado ou na consulta à API.
</Warning>

<Note>
  As entregas ficam visíveis no painel, com status HTTP e corpo da resposta, e é lá que você reenvia uma entrega que falhou.
</Note>


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