Listar webhooks
curl --request GET \
--url https://api.sandbox.z2pay.com/v1/webhooks \
--header 'x-api-key: <api-key>'const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://api.sandbox.z2pay.com/v1/webhooks', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.sandbox.z2pay.com/v1/webhooks"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text){
"data": [
{
"id": "<string>",
"name": "<string>",
"url": "<string>",
"events": [
"<string>"
],
"checkoutLinkIds": [
"<string>"
],
"isActive": true,
"hasSecret": true,
"secretHint": "<string>",
"autoDisabledAt": "2023-11-07T05:31:56Z",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}
],
"pagination": {
"page": 123,
"limit": 123,
"total": 123,
"totalPages": 123
}
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "Validation failed",
"issues": [
{
"path": "status",
"message": "Status inválido. Valores aceitos: pending, waiting_payment, paid, refused, canceled, refunded"
},
{
"path": "startDate",
"message": "Data deve ser ISO 8601 com timezone (ex.: 2026-06-24T00:00:00Z)"
}
]
}
}{
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid API key"
}
}Webhooks
Listar webhooks
Lista paginada dos webhooks da sua conta, com filtro por ativação e por evento assinado.
GET
/
webhooks
Listar webhooks
curl --request GET \
--url https://api.sandbox.z2pay.com/v1/webhooks \
--header 'x-api-key: <api-key>'const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://api.sandbox.z2pay.com/v1/webhooks', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.sandbox.z2pay.com/v1/webhooks"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text){
"data": [
{
"id": "<string>",
"name": "<string>",
"url": "<string>",
"events": [
"<string>"
],
"checkoutLinkIds": [
"<string>"
],
"isActive": true,
"hasSecret": true,
"secretHint": "<string>",
"autoDisabledAt": "2023-11-07T05:31:56Z",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}
],
"pagination": {
"page": 123,
"limit": 123,
"total": 123,
"totalPages": 123
}
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "Validation failed",
"issues": [
{
"path": "status",
"message": "Status inválido. Valores aceitos: pending, waiting_payment, paid, refused, canceled, refunded"
},
{
"path": "startDate",
"message": "Data deve ser ISO 8601 com timezone (ex.: 2026-06-24T00:00:00Z)"
}
]
}
}{
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid API key"
}
}GET /webhooks
Faz parte do recurso Webhooks — a configuração e o catálogo de eventos
estão lá.
Retorna a lista paginada dos webhooks da sua conta. Os dois filtros são opcionais e podem ser
combinados.
event responde “quem seria notificado se isso acontecesse”. Ele traz os webhooks inscritos
naquele evento, com correspondência exata e um valor por requisição — ?event=transaction.paid.
A lista de eventos válidos está em
Listar eventos disponíveis.O
secret não vem nesta resposta — nem em nenhuma outra leitura. Ele sai em claro uma única
vez, na criação do webhook. Aqui vêm no lugar hasSecret, que confirma
que o webhook assina as entregas, e secretHint, um fragmento para você reconhecer qual segredo
está configurado.Perdeu o valor? Não há como relê-lo, e nenhuma rota o troca: a rotação é feita no painel. Pela
API, o equivalente é criar outro webhook com o mesmo destino e remover o antigo.autoDisabledAt preenchido é um alarme. Significa que a Z2Pay desativou aquele webhook por
falhas seguidas, e nada está sendo entregue nele desde então. Vale uma varredura periódica por
este campo — o critério está em
Entrega e retentativas.Exemplo
curl -G https://api.sandbox.z2pay.com/v1/webhooks -H "x-api-key: SUA_CHAVE_DE_SANDBOX" --data-urlencode "isActive=true" --data-urlencode "limit=20"
{
"data": [
{
"id": "whk_k9clfafnldd96dbbxruh34233",
"name": "Notificações de pagamento",
"url": "https://meusite.com/webhooks/z2pay",
"events": ["transaction.paid", "transaction.refunded"],
"isActive": true,
"hasSecret": true,
"secretHint": "whsec_kQ8v…rS8t",
"autoDisabledAt": null,
"createdAt": "2026-06-24T13:45:00.000Z",
"updatedAt": "2026-06-24T13:45:00.000Z"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 1,
"totalPages": 1
}
}
Authorizations
API Key da Credential (gerada no Backoffice)
Query Parameters
Filtra por webhooks ativos (true) ou inativos (false). Omitido, traz ambos.
Available options:
true, false Retorna os webhooks inscritos neste evento. Um valor por requisição, correspondência exata (ex.: transaction.paid). A lista completa está em GET /webhooks/listeners.
Número da página a retornar.
Required range:
x > 0Quantidade de itens por página.
Required range:
0 < x <= 100