PayZu PixWebhooks e callbacks
Cadastrar webhooks
Receba os avisos de todas as transações da conta num endereço só, sem informar o endereço em cada chamada.
Cadastre o webhook
bash
curl -X POST https://pix.sandbox.payzu.dev/v1/user/webhooks \
-H "Authorization: Bearer SEU_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"url": "https://sualoja.com.br/webhook",
"events": ["TRANSACTION_COMPLETED", "TRANSACTION_REFUNDED"],
"generateSecret": true,
"active": true
}'json
{
"id": "cm3w7k1t40000q8f2r5b9x3ad",
"url": "https://sualoja.com.br/webhook",
"active": true,
"events": ["TRANSACTION_COMPLETED", "TRANSACTION_REFUNDED"],
"hasSecret": true,
"createdAt": "2026-08-10T12:00:00.000Z",
"updatedAt": "2026-08-10T12:00:00.000Z",
"secret": "q7Kx2mV9pL4sR8tW1nB6cY3hJ5dF0gZ-aE_uT7iO2kM"
}Referência: Cadastrar um webhook
| Campo | Regra |
|---|---|
url | http ou https, pública, sem usuário e senha e sem IPv6 literal. Fora disso, a resposta é 400. |
events | A lista de eventos; vazia, assina todos. |
generateSecret | Com true, a resposta traz o secret. Guarde: ele só aparece nesta resposta. |
active | false cadastra o webhook pausado. |
A conta tem até 5 webhooks ativos.
O sexto cadastro ativo, ou a reativação de um pausado além do limite, responde 409.
No sandbox, o webhook só recebe entregas depois de provar que a URL é sua.
Veja Webhooks no sandbox. Em produção não há essa etapa.
Depois do cadastro
Listar os webhooks
Veja os webhooks da conta e quais assinam as entregas.
Alterar um webhookTroque a URL ou os eventos, pause e reative.
Trocar o segredo de um webhookGere um segredo novo e invalide o anterior.
Excluir um webhookLibere a vaga entre os 5 ativos.
Contar as entregasConte as tentativas de entrega registradas.
Consultar uma entregaVeja o corpo enviado e a resposta do seu endpoint.
Erros desta operação
| Código | HTTP | Mensagem |
|---|---|---|
PZA204 | 403 | Conta bloqueada para alterações. Desbloqueie a conta antes de alterar. |
PZG409 | 409 | Limite de 5 webhooks ativos atingido |
Os códigos de autenticação e de validação estão no Catálogo de erros.