Skip to main content
Um webhook (whk_) é um endereço seu que a Z2Pay chama quando algo acontece na sua conta — uma transação foi paga, um saque foi recusado, uma fatura foi emitida. Você registra a URL, escolhe os eventos e passa a receber POST a cada ocorrência. Esta página cobre o cadastro. As outras três dividem o resto do assunto:
Todas as requisições usam o header x-api-key. Veja Autenticação. A base URL de sandbox é https://api.sandbox.z2pay.com/v1.

​
Endpoints

​
Cadastro

​
Entregas

​
O secret aparece uma vez só

O secret é a chave que assina cada entrega — é com ele que você confere que a requisição veio mesmo da Z2Pay, e não de alguém que descobriu a sua URL. Todo webhook tem um: enviar o campo no cadastro é opcional, e quando você não envia, a plataforma gera um (whsec_…, 256 bits) e o devolve na resposta.
A criação é a única resposta que devolve o secret em claro. Guarde-o no momento em que ele chega. As leituras trazem no lugar dois campos que confirmam a configuração sem expor o valor: hasSecret (booleano) e secretHint (whsec_abc…3pQ1).
Nenhuma rota troca o secret. Ele não é aceito no corpo do PATCH, e não existe endpoint de rotação — a troca é feita no painel. Se o valor vazou e você precisa girar agora, o caminho pela API é criar outro webhook com o mesmo destino e remover o antigo.
Como verificar a assinatura recebida está em Recebendo eventos.

​
Assinar tudo ou escolher

O campo events aceita os códigos do catálogo e trata a lista vazia como curinga:
  • events: ["transaction.paid"] — chega só esse evento.
  • events: [], ou o campo omitido — chega todos, inclusive os que forem criados depois.
A lista vazia vale também no PATCH. Enviar events: [] para “parar de receber” faz o contrário: assina tudo. Para silenciar um webhook, desative-o.
Código fora do catálogo é recusado com 400, então um evento escrito errado aparece no cadastro, não meses depois no silêncio.

​
O destino tem que ser público

A URL passa por duas barreiras: o cadastro recusa hosts internos, e cada envio resolve o DNS antes de conectar. São recusados localhost, as faixas privadas (10/8, 172.16/12, 192.168/16), o link-local e os endereços de metadata de nuvem (169.254/16, metadata.google.internal), o CGNAT (100.64/10) e qualquer esquema que não seja http ou https.
http é aceito para facilitar o sandbox, mas em produção use HTTPS — sem TLS, o payload e a assinatura trafegam legíveis.

​
Estados de uma entrega

Cada notificação enviada vira uma entrega (whd_), com o corpo que saiu daqui e a resposta que o seu servidor deu. São quatro estados:
failed é o que exige ação sua; retrying se resolve sozinho. O ciclo automático, os intervalos entre as tentativas e o que acontece quando o endpoint fica fora do ar estão em Entrega e retentativas.

​
Veja também

Recebendo eventos

Envelope, cabeçalhos e como verificar a assinatura HMAC.

Entrega e retentativas

O que acontece quando o seu servidor falha.

Catálogo de eventos

Cada evento e o payload que você recebe.

Erros

Formato de erro e status codes da API.