> ## 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.
# Remover webhook
> Apaga o cadastro de um webhook e encerra o envio de notificações para aquele endereço.
`DELETE /webhooks/:id`
Faz parte do recurso [Webhooks](/pt-BR/webhooks) — o cadastro e o catálogo de eventos estão lá.
Remove o webhook e devolve `200` com o registro removido. A partir daí nenhum evento é enviado
para aquele endereço.
**`deletedAt` preenchido é a confirmação da remoção.** Ele só aparece nesta resposta: as demais
leituras nunca devolvem registro removido — o webhook some da
[listagem](/pt-BR/webhooks/list) e passa a responder `404` na
[busca por ID](/pt-BR/webhooks/get).
**Não há como desfazer, e o `secret` vai junto.** Para voltar a receber é preciso
[criar outro webhook](/pt-BR/webhooks/create), que nasce com um segredo novo — o seu receptor
precisa passar a verificar a assinatura com ele.
Se a intenção é só parar por um tempo, [desative](/pt-BR/webhooks/status) em vez de remover: o
cadastro e o segredo permanecem.
**As entregas já registradas continuam consultáveis** em
[Listar deliveries](/pt-BR/webhooks/deliveries) — o histórico não é apagado com o cadastro. O que
não dá mais é [reprocessá-las](/pt-BR/webhooks/deliveries-retry): sem o webhook, o reenvio
responde `404 WEBHOOK_NOT_FOUND`.
## Exemplo
```bash theme={null}
curl -X DELETE https://api.sandbox.z2pay.com/v1/webhooks/whk_k9clfafnldd96dbbxruh34233 \
-H "x-api-key: SUA_CHAVE_DE_SANDBOX"
```
```json Resposta 200 theme={null}
{
"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:25:00.000Z",
"deletedAt": "2026-06-24T14:25:00.000Z"
}
```
## OpenAPI
````yaml openapi/psp.json DELETE /webhooks/{id}
openapi: 3.0.3
info:
title: Z2Pay PSP API
version: 1.0.0
description: API pública do PSP — autenticação via API Key (Credential)
servers:
- url: https://api.sandbox.z2pay.com/v1
description: Sandbox
- url: https://api.z2pay.com/v1
description: Produção
security: []
tags:
- name: Cards
description: Cartões salvos de um cliente
- name: Chargebacks
description: Gerenciamento de chargebacks
- name: Customers
description: Gerenciamento de clientes (compradores)
- name: Fees
description: Tabela de taxas da conta (pix, boleto, cartão, saque, refund, chargeback)
- name: Recipients
description: Gerenciamento de recebedores (sellers/merchants que recebem repasses)
- name: Refunds
description: Gerenciamento de reembolsos e estornos
- name: Splits
description: Regras de divisão do valor de uma venda entre recebedores
- name: Transactions
description: Gerenciamento de transações e payments
- name: Wallets
description: Saldo, extrato e resumo da carteira de um recebedor, agrupados por moeda
- name: Webhooks
description: Configuração, gerenciamento e histórico de entregas de webhooks
- name: Withdrawals
description: Solicitação e acompanhamento de saques (payouts) por recipient
paths:
/webhooks/{id}:
delete:
tags:
- Webhooks
summary: Remover webhook
description: >-
Remove um webhook (soft delete). Retorna a entidade com deletedAt
preenchido
operationId: WebhookController_remove
parameters:
- name: id
in: path
required: true
description: ID do webhook
schema:
type: string
- name: Idempotency-Key
in: header
required: false
description: Chave única para garantir idempotência da requisição
schema:
type: string
responses:
'200':
description: Webhook removido
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: Identificador único do registro.
name:
type: string
description: Nome do registro.
url:
type: string
format: uri
description: URL de destino do webhook ou link de download do arquivo.
events:
type: array
items:
type: string
description: Tipos de evento assinados pelo webhook.
isActive:
type: boolean
description: Indica se o registro está ativo.
hasSecret:
type: boolean
secretHint:
type: string
nullable: true
autoDisabledAt:
type: string
format: date-time
nullable: true
createdAt:
type: string
format: date-time
description: Data e hora de criação do registro (ISO 8601).
updatedAt:
type: string
format: date-time
description: Data e hora da última atualização do registro (ISO 8601).
deletedAt:
type: string
format: date-time
nullable: true
description: Data e hora de exclusão (soft delete); nulo se ativo.
required:
- id
- name
- url
- events
- isActive
- hasSecret
- secretHint
- autoDisabledAt
- createdAt
- updatedAt
- deletedAt
'401':
description: Chave de API ausente, malformada ou inválida
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
example:
error:
code: UNAUTHORIZED
message: Invalid API key
'404':
description: Webhook não encontrado
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
example:
error:
code: NOT_FOUND
message: Webhook not found
'409':
description: >-
Já existe uma requisição em andamento com esta Idempotency-Key. A
API aguarda a primeira concluir por até 5 segundos antes de
responder assim
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: >-
Mensagem do conflito de idempotência. Aqui `error` é
texto, não objeto — ramifique pelo status HTTP.
example:
error: A request with this idempotency key is already being processed
'422':
description: >-
Idempotency-Key já usada com um corpo diferente. Use uma chave nova
para uma operação diferente
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: >-
Mensagem do conflito de idempotência. Aqui `error` é
texto, não objeto — ramifique pelo status HTTP.
example:
error: Idempotency key already used with a different request body
security:
- apiKey: []
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: API Key da Credential (gerada no Backoffice)
````