Cadastrar webhooks
Receba numa URL sua os eventos que você escolher de toda a conta, com quantos webhooks precisar, cada um com a própria URL e o próprio segredo.
Cadastre o webhook
Envie a url e a lista events, com nomes da tabela de eventos. Para cadastrar o webhook pausado, envie também isActive: false.
curl --request POST \
--url 'https://api.sandbox.payzu.dev/api/v1/transactions/webhooks' \
--header 'Authorization: Bearer SEU_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"url": "https://sualoja.com.br/webhooks/payzu",
"events": ["PAYMENT_PAID", "PAYMENT_EXPIRED", "WITHDRAW_COMPLETED", "WITHDRAW_FAILED"]
}'{
"id": "cmu6w1h0k000101s6ef34gh56",
"url": "https://sualoja.com.br/webhooks/payzu",
"events": ["PAYMENT_PAID", "PAYMENT_EXPIRED", "WITHDRAW_COMPLETED", "WITHDRAW_FAILED"],
"isActive": true,
"createdAt": "2026-10-01T12:00:00.000Z",
"updatedAt": "2026-10-01T12:00:00.000Z",
"secret": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
}Referência: Cadastrar um webhook
O secret aparece só nesta resposta e assina todos os avisos deste webhook.
Guarde-o no seu cofre antes de seguir: nenhuma rota da API lê ou troca o segredo de um webhook. Se perdê-lo, gere outro no painel, na tela de webhooks, com Novo segredo e o PIN de operação. O anterior para de valer na hora, e as novas tentativas e os reenvios já saem assinados com o novo.
Depois de cadastrar, você pode listar, alterar ou excluir o webhook.
Erros desta operação
| Código | HTTP | Mensagem |
|---|---|---|
WEBHOOK_DUPLICATED_URL | 409 | Já existe um webhook com esta URL nesta conta. |
Todos os códigos do PayZu Conta Hub estão no Catálogo de erros.