PayZu GatewayWebhooks
Cadastrar webhooks
Receba os avisos da conta em até 5 endereços do seu sistema, cada um só com os eventos de que ele precisa.
Cadastre o webhook
bash
curl -X POST https://api.sandbox.payzu.dev/v1/webhooks \
-H "Authorization: Bearer SUA_CHAVE_DE_API" \
-H "Content-Type: application/json" \
-d '{
"url": "https://loja.exemplo.com.br/webhooks/payzu",
"description": "Sistema de pedidos",
"events": ["invoice.paid", "invoice.refunded"]
}'json
{
"id": "whe_oeQa3G4R1B4IW9KNJAiP1l",
"status": "active",
"url": "https://loja.exemplo.com.br/webhooks/payzu",
"description": "Sistema de pedidos",
"events": ["invoice.paid", "invoice.refunded"],
"masked_secret": "****0000",
"secret": "-lobN1qfwI-_xHx6ob6wrpxnjw496IapHJDV2xW0000",
"created_at": "2026-11-11T15:20:59.433Z",
"updated_at": "2026-11-11T15:20:59.433Z"
}Referência: Cadastrar um webhook
Guarde o segredo que vem na resposta.
O secret só aparece nesta resposta e na troca do segredo. É com ele que você confere a assinatura de cada aviso.
O webhook nasce active. O cadastro ignora o cabeçalho Idempotency-Key: repetir a chamada cria outro webhook.
Campos
| Campo | Regra |
|---|---|
url | Obrigatório. Segue as regras da URL, abaixo. |
events | Obrigatório. Lista com pelo menos um dos eventos. |
description | Opcional. De 1 a 120 caracteres. |
Regras da URL
- Usa
httpsna porta 443. - Não tem usuário nem senha.
- Não aponta para endereço interno, para
localhostnem para domínio que resolve para endereço interno. - Não aponta para domínio de serviço do Google Cloud:
*.run.app,*.cloudfunctions.net,*.appspot.com,*.googleapis.com,*.googe*.internal.
A conta tem até 5 webhooks, ativos ou pausados.
Para cadastrar o sexto, exclua um webhook e libere a vaga.
Erros desta operação
| Código | HTTP | Mensagem |
|---|---|---|
PZ750 | 400 | URL inválida. A URL não pode ter usuário ou senha. A URL precisa usar https. A URL precisa usar a porta 443. A URL aponta para um endereço interno. A URL aponta para um serviço interno do Google Cloud. Use um domínio próprio. A URL resolve para um endereço interno. |
PZ751 | 422 | Limite de 5 webhooks atingido. Apague um antes de criar outro. |
Os erros de autenticação e de validação estão no Catálogo de erros.