Ativar/desativar webhook
curl --request PATCH \
--url https://api.sandbox.z2pay.com/v1/webhooks/{id}/status \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"isActive": true
}
'const options = {
method: 'PATCH',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({isActive: true})
};
fetch('https://api.sandbox.z2pay.com/v1/webhooks/{id}/status', 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/{id}/status"
payload = { "isActive": True }
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text){
"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"
}{
"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"
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Webhook not found"
}
}{
"error": "A request with this idempotency key is already being processed"
}{
"error": "Idempotency key already used with a different request body"
}Webhooks
Ativar/desativar webhook
Liga e desliga o envio de notificações sem apagar o cadastro.
PATCH
/
webhooks
/
{id}
/
status
Ativar/desativar webhook
curl --request PATCH \
--url https://api.sandbox.z2pay.com/v1/webhooks/{id}/status \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"isActive": true
}
'const options = {
method: 'PATCH',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({isActive: true})
};
fetch('https://api.sandbox.z2pay.com/v1/webhooks/{id}/status', 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/{id}/status"
payload = { "isActive": True }
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text){
"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"
}{
"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"
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Webhook not found"
}
}{
"error": "A request with this idempotency key is already being processed"
}{
"error": "Idempotency key already used with a different request body"
}PATCH /webhooks/:id/status
Faz parte do recurso Webhooks — o cadastro e o catálogo de eventos estão lá.
Liga e desliga o webhook mantendo URL, eventos e secret. É o caminho certo para pausar as
notificações durante uma manutenção do seu servidor, e o único jeito de reativar um webhook que a
Z2Pay desativou sozinho.
Enquanto está inativo, os eventos não são guardados. Nada fica em fila esperando: o que
acontecer nesse período simplesmente não vira entrega, e reativar não reenvia nada. Para
fechar a lacuna depois, consulte a API pelos recursos daquele período — o passo a passo está em
Entrega e retentativas.
Reativar limpa o
autoDisabledAt. Se o webhook tinha sido desativado automaticamente por
falhas, isActive: true o traz de volta e zera o marcador. Vale conferir que o endpoint já está
respondendo 2xx antes — desativado de novo, o ciclo recomeça.Exemplo
curl -X PATCH https://api.sandbox.z2pay.com/v1/webhooks/whk_k9clfafnldd96dbbxruh34233/status \
-H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
-H "Content-Type: application/json" \
-d '{ "isActive": false }'
Resposta 200
{
"id": "whk_k9clfafnldd96dbbxruh34233",
"name": "Notificações de pagamento",
"url": "https://meusite.com/webhooks/z2pay",
"events": ["transaction.paid", "transaction.refunded"],
"isActive": false,
"hasSecret": true,
"secretHint": "whsec_kQ8v…rS8t",
"autoDisabledAt": null,
"createdAt": "2026-06-24T13:45:00.000Z",
"updatedAt": "2026-06-24T14:20:00.000Z"
}
Authorizations
API Key da Credential (gerada no Backoffice)
Headers
Chave única para garantir idempotência da requisição
Path Parameters
ID do webhook
Body
application/json
Ativa (true) ou desativa (false) o webhook.
Response
Status do webhook atualizado
Identificador único do registro.
Nome do registro.
URL de destino do webhook ou link de download do arquivo.
Tipos de evento assinados pelo webhook.
Indica se o registro está ativo.
Data e hora de criação do registro (ISO 8601).
Data e hora da última atualização do registro (ISO 8601).