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

# Como funcionam os webhooks

> Quem avisa quem, o que a sua URL precisa ter e o que acontece quando ela cai.

Quando algo acontece com o seu dinheiro, a WyzeCash faz um `POST` na sua URL com o evento em JSON. É assim que você sabe que o Pix caiu sem ficar consultando a API.

## Onde configurar

Tudo fica em **Integrações e API › Webhooks**, no painel, só com a sua sessão: a chave de API não configura webhooks, então uma chave vazada não desvia os seus eventos.

**1. Copie o segredo da conta**

Um segredo `whsec_...` é criado no primeiro acesso. Ele assina todos os envios. Guarde no seu servidor; dá para gerar outro a qualquer hora (o antigo para na hora).

**2. Cadastre as URLs**

Até **cinco URLs**, todas recebem **todo** evento da conta, cada uma com a própria fila de reentrega. Cada URL pode ter um segredo próprio em vez do da conta.

**3. Envie um teste**

O botão **Enviar teste** manda o evento `webhook.test` para todas as URLs. Confira a assinatura e responda `2xx`.

**4. Acompanhe os envios**

A aba lista cada envio com situação (Entregue, Na fila, Falhou, Sem destino), código HTTP, tempo, tentativas e o corpo enviado. Dá para **reenviar** qualquer um.

> [!NOTE]
>
> Com mais de uma URL, cada uma recebe uma cópia do evento com o mesmo `id` (`evt_...`) e a mesma assinatura. Se dois dos seus sistemas gravam no mesmo banco, deduplique pelo `id` nos dois.

## O que cada URL precisa ter

| Requisito | Detalhe |
| - | - |
| HTTPS | Obrigatório. `http://` é recusado ao salvar |
| Domínio público | `localhost`, IP privado, redes internas e metadados de nuvem são bloqueados (ao salvar e de novo antes de cada envio) |
| Sem redirecionamento | A WyzeCash não segue `3xx`; aponte direto para a rota |
| Sem usuário e senha na URL | Use o segredo da assinatura, não `https://user:pass@` |
| Responder `2xx` em até 10 s | Responda primeiro, processe depois (fila, job) |
| Ler o corpo cru | A assinatura é calculada sobre os bytes exatos; não reserialize o JSON |

## Cabeçalhos

| Cabeçalho | O que é |
| - | - |
| `Content-Type` | `application/json` |
| `X-Bukio-Event` | o `type` do evento (ex.: `payment.paid`) |
| `X-Bukio-Delivery` | identificador deste envio (muda a cada tentativa) |
| `X-Bukio-Signature` | `t=<unix>,v1=<hex>`: veja [Validando a assinatura](https://docs.wyzecash.com.br/webhooks/assinatura.md) |

## Corpo

```json theme={null}
{
  "id": "evt_01JA7X9K2M4Q8W3Z5F6H1N0P",
  "type": "payment.paid",
  "created_at": "2026-10-08T15:04:12.318Z",
  "data": { "id": "BKY-7KQ2M9XP4RZT", "...": "..." }
}
```

| Campo | O que é |
| - | - |
| `id` | identificador do evento (`evt_`), o mesmo em todas as URLs e em todo reenvio |
| `type` | qual evento |
| `created_at` | quando aconteceu (ISO 8601, UTC) |
| `data` | o recurso; `data.id` é sempre o código com prefixo (`BKY-`, `SAQ-`...). Valores em centavos |

## Reentrega

Sem `2xx` em 10 s (ou sem resposta), a WyzeCash tenta de novo em **1 min, 5 min, 15 min, 1 h, 3 h, 6 h e 12 h** (8 tentativas no total). Depois disso o envio fica como "Falhou" no painel, de onde você reenvia manualmente. De cada tentativa ficam o código HTTP, o tempo e o começo do corpo que a sua URL respondeu (até 2.000 caracteres), que aparecem no detalhe do envio no painel. O histórico de envios fica 30 dias.

## Eventos

| Evento | Quando | `data.id` | Página |
| - | - | - | - |
| `payment.created` · `payment.paid` · `payment.expired` · `payment.refunded` | cobrança criada, paga, expirada ou estornada | `BKY-` | [Cobranças](https://docs.wyzecash.com.br/webhooks/cobrancas.md) |
| `withdrawal.requested` · `withdrawal.completed` · `withdrawal.failed` | saque pedido, concluído, não realizado ou recusado | `SAQ-` / `SAQ-API-` | [Saques](https://docs.wyzecash.com.br/webhooks/saques.md) |
| `pix.sent` · `pix.failed` | só da rota antiga `/v1/pix/payments`, que vai ser removida (use o saque e os eventos `withdrawal.*`) | `ENV-` | [Saques](https://docs.wyzecash.com.br/webhooks/saques.md) |
| `transfer.received` · `transfer.sent` | transferência entre contas WyzeCash recebida ou enviada | `TRF-` | [Transferências](https://docs.wyzecash.com.br/webhooks/transferencias.md) |
| `subaccount.credited` · `subaccount.debited` | entrou ou saiu dinheiro de uma subconta (venda, envio, transferência, saque, devolução, estorno, MED) | `SUB-` | [Subcontas](https://docs.wyzecash.com.br/webhooks/subcontas.md) |
| `webhook.test` | botão "Enviar teste" | `TESTE` | [Transferências](https://docs.wyzecash.com.br/webhooks/transferencias.md#teste) |

O provedor Pix por trás de cada operação **nunca** aparece no webhook.

## O jeito certo de tratar

1. Leia o corpo **cru** antes de qualquer parse.
2. Valide `X-Bukio-Signature`. Inválida: responda `400` e ignore.
3. Guarde o `id` do evento e ignore repetidos.
4. Responda `2xx` em menos de 10 s; faça o trabalho pesado depois.
5. Trate pelo `type` e pelo `data.id`, nunca pela ordem de chegada: `payment.paid` pode chegar antes de `payment.created`.
6. Em dúvida, consulte a API: `GET /v1/payments/{id}` é sempre a verdade atual.

## Pausa pela equipe WyzeCash

Uma URL que falha por muito tempo pode ser pausada pela equipe, com um motivo que aparece no painel; você recebe um aviso de segurança. Corrija o servidor e reative.

## IP de origem

Não dependa do IP de origem dos envios: confira sempre o `X-Bukio-Signature`. Se o seu firewall exige liberar um IP, fale com o suporte WyzeCash.


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