Webhooks
Nesta página
Cadastre o webhookEventosO que chega no seu endpointAssinaturaResposta esperada e retentativasReceba no seu sistema um aviso quando um depósito, uma compra ou um saque termina.
Cadastre o webhook
Você cadastra o webhook no painel da Exchange, em Conta e ajustes, na entrada API e webhooks, com a URL e os eventos que ela deve receber.
- URL: usa
httpse aponta para um domínio público. - Limite: até 5 webhooks por conta.
O segredo da assinatura aparece uma única vez.
Ele é mostrado na criação e na troca do segredo. Copie e guarde no cofre de segredos da sua aplicação.
Eventos
| Evento | Quando dispara |
|---|---|
deposit.confirmed | O depósito foi confirmado. |
deposit.failed | O depósito não foi concluído. |
buy.settled | A compra foi concluída. |
buy.refunded | A compra foi devolvida. |
withdrawal.confirmed | O saque foi confirmado. |
withdrawal.failed | O saque falhou. |
withdrawal.expired | O saque expirou. |
O que chega no seu endpoint
POST /payzu/webhook HTTP/1.1
Host: suaempresa.com.br
Content-Type: application/json
User-Agent: PayZu-Exchange-Webhooks/1
PayZu-Event-Id: evt_9a1f6b2e-1c7d-4f0e-8b44-2d3f5c6a7e80
PayZu-Event-Type: withdrawal.confirmed
PayZu-Delivery-Id: 3f6c1b9e-7a2d-4e5f-9c81-0b4d6e2a7f13
PayZu-Delivery-Attempt: 1
PayZu-Signature: t=1762776001,v1=5f1c2e9a0b7d4c6e8f1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f70
{"id":"evt_9a1f6b2e-1c7d-4f0e-8b44-2d3f5c6a7e80","type":"withdrawal.confirmed","version":1,"occurredAt":"2026-11-10T12:00:00.000Z","createdAt":"2026-11-10T12:00:01.512Z","accountNumber":"900123","data":{"code":"RW-2","kind":"withdrawal","status":"confirmed", … }}data traz a movimentação no formato de Consultar detalhes da movimentação. PayZu-Delivery-Attempt conta as tentativas a partir de 1. Os headers e o corpo de cada evento estão na página dele.
Assinatura
Os avisos chegam assinados no cabeçalho PayZu-Signature. O cálculo e o código para conferir estão em Assinatura dos webhooks.
Resposta esperada e retentativas
| Situação | O que a PayZu faz |
|---|---|
Qualquer 2xx em até 10 segundos | Conclui a entrega. |
Sem 2xx nesse prazo, inclusive com redirecionamento | Repete a entrega, até 10 tentativas. |
| 20 entregas seguidas que esgotaram as tentativas | Pausa o webhook. Para retomar, salve o webhook no painel. |
O mesmo aviso pode chegar mais de uma vez e fora de ordem.
Deduplique pelo PayZu-Event-Id, que é igual em todas as tentativas.