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.

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

​

Corpo

{
  "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
withdrawal.requested · withdrawal.completed · withdrawal.failed	saque pedido, concluído, não realizado ou recusado	SAQ- / SAQ-API-	Saques
pix.sent · pix.failed	só da rota antiga /v1/pix/payments, que vai ser removida (use o saque e os eventos withdrawal.*)	ENV-	Saques
transfer.received · transfer.sent	transferência entre contas WyzeCash recebida ou enviada	TRF-	Transferências
subaccount.credited · subaccount.debited	entrou ou saiu dinheiro de uma subconta (venda, envio, transferência, saque, devolução, estorno, MED)	SUB-	Subcontas
webhook.test	botão “Enviar teste”	TESTE	Transferências

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.