PayZu Câmbio

Webhooks


Nesta páginaCadastre o webhookEventosO que chega no seu endpointAssinaturaResposta esperada e retentativas

Receba no seu sistema um aviso quando um depósito, uma compra ou um saque termina.

Fluxo de um webhook: o evento vira um POST assinado no seu endpoint, que conclui a entrega com 2xx em até 10 segundos ou recebe novas tentativas

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 https e 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

EventoQuando dispara
deposit.confirmedO depósito foi confirmado.
deposit.failedO depósito não foi concluído.
buy.settledA compra foi concluída.
buy.refundedA compra foi devolvida.
withdrawal.confirmedO saque foi confirmado.
withdrawal.failedO saque falhou.
withdrawal.expiredO saque expirou.

O que chega no seu endpoint

Entrega de um webhook
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çãoO que a PayZu faz
Qualquer 2xx em até 10 segundosConclui a entrega.
Sem 2xx nesse prazo, inclusive com redirecionamentoRepete a entrega, até 10 tentativas.
20 entregas seguidas que esgotaram as tentativasPausa 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.