Excluir um endpoint

Remove permanentemente um endpoint de webhook (a URL cadastrada para receber notificações da Selectwin). A partir da exclusão, aquela URL deixa de receber qualquer evento — use quando uma integração for desativada, migrada para outra URL ou comprometida.

DELETE /v1/webhooks/endpoints/{endpointId}

Um webhook é uma notificação HTTP que a Selectwin envia ao seu servidor quando algo acontece (por exemplo, uma transação é aprovada). O endpoint é o cadastro que guarda a URL de destino, os eventos assinados e o segredo de assinatura. Excluir o endpoint apaga esse cadastro.

Como funciona

A operação é síncrona e definitiva: assim que a API responde 200 OK, o endpoint deixa de existir e nenhum evento futuro será entregue àquela URL.

O que a exclusão faz:

• Para a entrega imediatamente. Eventos que dispararem depois da exclusão não são enviados para esta URL. Se você tiver outros endpoints assinando os mesmos eventos, eles continuam recebendo normalmente — a exclusão afeta só este endpoint.
• Cancela tentativas pendentes de entrega que ainda estavam na fila/retry para este endpoint.
• Invalida o segredo de assinatura (whsec_…) deste endpoint. Ao recriar o endpoint com Create, você recebe um novo segredo — atualize o código de verificação de assinatura.
• É irreversível. Não há "lixeira" nem desfazer. Para uma pausa temporária, não exclua: ajuste a inscrição abaixo.

A resposta usa o formato de confirmação (mantido para clientes legados): em vez de devolver o objeto do endpoint, ela devolve um envelope com deleted: true e links HATEOAS (_links) apontando para as próximas ações possíveis (criar e listar). HATEOAS = links que a própria API fornece para você navegar entre operações relacionadas sem montar URLs na mão.

Quando usar (e quando não)

Use DELETE quando:

• A integração foi descontinuada e a URL não deve mais receber nada.
• Houve mudança de infraestrutura e a URL antiga será desligada de vez.
• O endpoint foi comprometido (segredo vazado, URL maliciosa) e você quer eliminá-lo por completo.

Não use DELETE quando:

• Você só quer pausar temporariamente. Em vez disso, reduza a inscrição via Update — esvazie ou ajuste a lista de events (ou desligue forceActivities) para parar de receber sem apagar o cadastro. Assim você preserva id, secret e histórico, e pode reinscrever os eventos depois. (Não há campo de corpo enabled para alterar aqui — gerencie pela lista de events.)
• Você só quer mudar a URL ou os eventos. Faça isso com Update, sem perder o id nem o segredo.

Requisição

Headers

Não há corpo nesta requisição, portanto Content-Type é dispensável. A autenticação é sempre pelo header SelectKey — nunca Authorization: Bearer ou Basic.

Parâmetros de caminho

Exemplo curl

curl -X DELETE https://api.selectwin.io/v1/webhooks/endpoints/wbe_01hqzvabc \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Resposta

Sucesso (200 OK)

{
  "id": "wbe_01hqzvabc",
  "resource": "webhook",
  "deleted": true,
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": {
    "self": {
      "href": "https://api.selectwin.io/v1/webhooks/endpoints/wbe_01hqzvabc",
      "method": "DELETE",
      "description": "Delete the webhook endpoint."
    },
    "create": {
      "href": "https://api.selectwin.io/v1/webhooks/endpoints",
      "method": "POST",
      "description": "Create a new webhook endpoint."
    },
    "list": {
      "href": "https://api.selectwin.io/v1/webhooks/endpoints",
      "method": "GET",
      "description": "List all webhook endpoints."
    }
  }
}

Erros

Trate sempre pelo error.code (estável), nunca pela message. Veja o Catálogo de Códigos de Erro e o envelope de erro.

Exemplo de 404 (endpoint inexistente ou já removido):

{
  "error": {
    "code": "notFound",
    "statusCode": 404,
    "category": "client",
    "message": "Webhook endpoint not found."
  }
}

Boas práticas

• Prefira pausar a excluir quando houver chance de reativação: use Update para esvaziar/ajustar os events (ou desligar forceActivities) em vez de DELETE. Você mantém id, secret e histórico.
• Guarde a configuração antes de apagar. Leia o endpoint (URL, eventos, metadata) e armazene; o segredo (whsec_…) não pode ser recuperado depois.
• Confirme pelo campo deleted (e não apenas pelo HTTP 200) antes de remover referências internas ao endpoint.
• Trate 404 como sucesso quando a meta for "garantir que não exista" — isso torna a operação segura para repetir.
• Não precisa de X-Idempotency-Key aqui: DELETE é naturalmente idempotente. Para tentativas repetidas (rede instável, retry), basta tratar 404 como sucesso — o resultado é o mesmo.
• Tenha a substituição pronta antes de excluir um endpoint que está sendo trocado: crie e valide o novo endpoint com Create e só então remova o antigo, evitando janela sem entregas.
• Atualize a verificação de assinatura no seu lado: o segredo do endpoint excluído deixa de valer; um endpoint recriado terá um segredo novo.

Veja também

• Visão geral de Webhook Endpoints — o modelo do objeto e o ciclo de vida.
• Create — recriar um endpoint (gera novo id e secret).
• Update — pausar (ajustando events) ou alterar sem excluir.
• List — listar endpoints para conferir o id antes de apagar.
• Analyze — estatísticas de entrega do endpoint.
• Idempotência · Autenticação · Convenções