Webhooks e callbacks
Nesta página
Como integrarDois canaisEventosO que chega no seu endpointResposta esperada e retentativasConfira o que foi entregueReceba no seu sistema um aviso a cada mudança de uma transação, como cobrança paga, saque concluído, devolução terminada ou infração MED aberta.
Como integrar
Crie o segredo que assina os avisos enviados ao callbackUrl.
Receba os eventos de todas as transações da conta num endereço só.
3. Modelo de callbackVeja o corpo comum a todo aviso e como identificar o evento.
4. Assinatura dos callbacksConfira o cabeçalho X-Callback-Signature antes de processar.
Peça de novo os avisos que o seu endpoint perdeu.
Webhooks no sandboxProve que a URL é sua para receber as entregas de teste.
Dois canais
callbackUrl da transação | Webhook da conta | |
|---|---|---|
| Onde se configura | Campo callbackUrl em POST /pix, POST /withdraw, POST /withdraw/qrcode e POST /internal-transfer | POST /user/webhooks, até 5 ativos por conta |
| Alcance | Só a transação criada com ele | Todas as transações da conta |
| Quando chega | Em toda atualização depois da criação, mesmo sem troca de status, e nos avisos de infração | Em cada troca de status, inclusive a criação (TRANSACTION_PENDING), em cada devolução concluída e em INFRACTION_CHANGED |
| Não recebe | A criação da cobrança ou do saque e a troca de status feita pela PayZu. A devolução feita pelo MED pode não chegar | Atualização sem troca de status, menos a devolução parcial concluída |
| Filtro por evento | Não tem | Lista events; vazia recebe todos |
Cabeçalho X-Callback-Event | Não vem | Vem em toda entrega |
Uma conta pode usar os dois canais ao mesmo tempo.
Eventos
| Evento | Quando dispara |
|---|---|
TRANSACTION_PENDING | A cobrança ou o saque foi criado e aguarda liquidação. |
TRANSACTION_COMPLETED | O Pix foi liquidado. |
TRANSACTION_CANCELED | A transação foi encerrada sem liquidar. |
TRANSACTION_EXPIRED | A instituição confirmou que a cobrança venceu sem pagamento. |
TRANSACTION_WAITING_FOR_REFUND | A instituição informou a devolução em processamento. |
TRANSACTION_REFUNDED | Uma devolução, total ou parcial, foi concluída. |
TRANSACTION_ERROR | A transação terminou em erro. |
INFRACTION_CHANGED | Uma infração MED foi aberta ou atualizada. |
Cada evento leva o nome do novo status da transação, com duas exceções:
- Devolução parcial: chega como
TRANSACTION_REFUNDED, comstatus: COMPLETEDenquanto a soma devolvida não alcança o valor da transação. Quando alcança, ostatuséREFUNDED. INFRACTION_CHANGED: a transação chega com o status que já tinha, junto do objetoinfraction. O reenvio pode vir sem ele.
O cadastro aceita também TRANSACTION_SUSPECTED_FRAUD e TRANSACTION_SUSPECTED_FRAUD_REVERSAL, que hoje não são disparados.
O que chega no seu endpoint
| Cabeçalho | O que traz |
|---|---|
X-Callback-Event | O evento, só nas entregas de webhook. O aviso do callbackUrl se identifica pelo corpo. |
X-Callback-Attempt | O número da tentativa, a partir de 1. |
X-Callback-Signature | A assinatura, nos canais com segredo. Veja Assinatura dos callbacks. |
User-Agent | Callback-Service/1.0. |
O corpo comum a todo aviso está em Modelo de callback. Os headers e o corpo de cada evento estão na página dele, linkada na tabela de eventos.
Resposta esperada e retentativas
| Regra | Como funciona |
|---|---|
| Resposta esperada | Qualquer status 2xx em até 5 segundos. O corpo da sua resposta não muda nada; ele só fica no histórico. |
| Falha | Outro status, timeout ou conexão recusada fazem a entrega voltar para a fila. |
| Tentativas | Até 12 no total, a primeira e 11 retentativas. |
| Espera | A espera nominal começa em 5 min e dobra a cada vez (5, 10, 20… min); cada espera é sorteada entre metade e o valor cheio. A última tentativa sai entre cerca de 3,5 e 7 dias depois da primeira. |
| Nova tentativa | Lê a transação de novo e sai com o estado atual e uma assinatura nova. |
| Redirecionamento | Responda 2xx direto, sem redirecionar. |
| Resposta com mais de 1 MB | Conta como falha. |
| Destino interno ou reservado | É recusado sem retentativa. |
| Registro | Cada tentativa enviada fica registrada com o status HTTP retornado (-1 quando não houve resposta), o corpo e os cabeçalhos da resposta e o tempo de resposta. |
Um evento de webhook cujo status já mudou quando a entrega sai é descartado.
Não há tentativa, retentativa nem registro no histórico. O evento do status novo segue por conta própria, se o webhook o assinar. A exceção é o TRANSACTION_REFUNDED da devolução parcial, com a transação ainda COMPLETED: ele sai normalmente. Webhook pausado ou excluído também descarta o que estava na fila.
O mesmo aviso pode chegar mais de uma vez.
Isso acontece por retentativa, reenvio ou pelos dois canais. Trate o aviso pelo estado que o corpo traz, porque uma nova tentativa relê a transação. Deduplique os avisos de transação por id + updatedAt. Em INFRACTION_CHANGED, use só infraction.id + infraction.updatedAt, porque o updatedAt da transação não muda com a infração. Para ordenar, compare updatedAt nos avisos de transação e infraction.updatedAt nos de infração. O reenvio de INFRACTION_CHANGED pode vir sem infraction: consulte a infração em GET /user/infractions, com o id da transação no filtro transactionId.
Confira o que foi entregue
| Para | Use |
|---|---|
| Ver as tentativas dos dois canais | Histórico de callbacks |
| Ver uma entrega de webhook | Consultar uma entrega |
| Recuperar falhas antigas | Reenviar callbacks |