> ## Documentation Index
> Fetch the complete documentation index at: https://docs.z2pay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhooks (gerenciamento)
> Cadastro dos endereços que recebem as notificações da Z2Pay, o catálogo de eventos e o histórico de entregas.
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:
| Página | Responde |
| -------------------------------------------------- | ---------------------------------------------------------------------- |
| [Recebendo eventos](/pt-BR/webhooks/visao-geral) | O que você implementa: envelope, cabeçalhos, verificação da assinatura |
| [Entrega e retentativas](/pt-BR/webhooks/entregas) | O que a Z2Pay faz: reenvio automático, desativação, reconciliação |
| [Catálogo de eventos](/pt-BR/webhooks/eventos) | Quais eventos existem e o que cada um carrega |
Todas as requisições usam o header `x-api-key`. Veja [Autenticação](/pt-BR/autenticacao).
A base URL de sandbox é `https://api.sandbox.z2pay.com/v1`.
***
## Endpoints
### Cadastro
| Método | Rota | Descrição |
| -------- | ----------------------- | ------------------------------------------- |
| `POST` | `/webhooks` | Registra um webhook |
| `GET` | `/webhooks` | Lista paginada dos webhooks |
| `GET` | `/webhooks/listeners` | Catálogo de eventos que podem ser assinados |
| `GET` | `/webhooks/{id}` | Busca um webhook por ID |
| `PATCH` | `/webhooks/{id}` | Atualiza nome, URL e eventos |
| `PATCH` | `/webhooks/{id}/status` | Ativa ou desativa |
| `DELETE` | `/webhooks/{id}` | Remove |
### Entregas
| Método | Rota | Descrição |
| ------ | --------------------------------- | ---------------------------------------- |
| `GET` | `/webhooks/deliveries` | Lista paginada das tentativas de entrega |
| `GET` | `/webhooks/deliveries/{id}` | Busca uma entrega por ID |
| `POST` | `/webhooks/deliveries/{id}/retry` | Reenvia uma entrega concluída |
***
## 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](/pt-BR/webhooks/create) é 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`](/pt-BR/webhooks/update), 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](/pt-BR/webhooks/create) com o mesmo destino e
[remover](/pt-BR/webhooks/delete) o antigo.
Como verificar a assinatura recebida está em
[Recebendo eventos](/pt-BR/webhooks/visao-geral#verificando-a-assinatura).
***
## Assinar tudo ou escolher
O campo `events` aceita os códigos do [catálogo](/pt-BR/webhooks/listeners) 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`](/pt-BR/webhooks/update).** Enviar `events: []` para
"parar de receber" faz o contrário: assina tudo. Para silenciar um webhook,
[desative-o](/pt-BR/webhooks/status).
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:
| Status | O que significa |
| ---------- | --------------------------------------- |
| `pending` | Na fila, ainda não enviada |
| `retrying` | Falhou e será reenviada automaticamente |
| `success` | Seu servidor respondeu `2xx` |
| `failed` | Esgotou as tentativas automáticas |
**`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](/pt-BR/webhooks/entregas).
***
## Veja também
Envelope, cabeçalhos e como verificar a assinatura HMAC.
O que acontece quando o seu servidor falha.
Cada evento e o payload que você recebe.
Formato de erro e status codes da API.