Atualizar um endpoint

Altere a configuração de um endpoint de webhook existente — sua URL de destino, os tipos de evento inscritos, o cabeçalho de autenticação ou os metadados. Use quando precisar redirecionar entregas após uma migração de servidor, ajustar quais eventos você recebe ou rotacionar credenciais, sem ter que apagar e recriar o endpoint (o que mudaria o id e o secret).

PUT /v1/webhooks/endpoints/{endpointId}

Um webhook é uma notificação HTTP que a Selectwin envia para a sua URL quando algo acontece na sua conta (uma transação aprovada, um reembolso, etc.). O endpoint é o registro que guarda essa URL, a lista de eventos que você quer receber e como autenticar as entregas. Esta operação edita esse registro.

Como funciona

A atualização é síncrona: o servidor valida o corpo, grava as mudanças e responde na hora com o endpoint já atualizado (HTTP 200). A partir do próximo evento, as entregas passam a respeitar a nova configuração.

Pontos importantes do comportamento:

• O id e o secret não mudam. Atualizar o endpoint preserva o identificador (wbe_...) e o segredo de assinatura criado no Create. Sua verificação de assinatura HMAC continua funcionando sem ajustes. Para trocar o segredo, recrie o endpoint.
• Substituição, não mesclagem, em campos enviados. Cada campo presente no corpo substitui o valor anterior. Em particular, events é a lista completa de eventos — enviar ["transaction.approved"] deixa o endpoint inscrito somente nesse evento; os demais são removidos. Para acrescentar um evento, envie a lista antiga mais o novo.
• Atualização parcial. Campos omitidos do corpo mantêm o valor atual. Você pode, por exemplo, enviar só endpoint para trocar a URL sem mexer nos eventos.
• Entregas em andamento não são interrompidas. Eventos já enfileirados para a configuração anterior podem ainda ser entregues; a mudança vale para os eventos seguintes.
• A resposta não repete o secret nem expõe merchant/_links — é o objeto do endpoint puro, com authorization.value mascarado.

Quando usar

• Trocar a URL de destino após mudar de servidor, domínio ou ambiente.
• Ajustar a lista de events para receber mais ou menos tipos de notificação.
• Atualizar o cabeçalho de authorization (rotação de token).
• Corrigir o name ou ajustar metadata.

Quando NÃO usar:

• Para trocar o segredo de assinatura: não há campo para isso — apague com Delete e recrie com Create.
• Para só consultar a configuração atual: use o read (GET .../{endpointId}).
• Para ativar/desativar entregas sem perder o registro: a flag enabled aparece na resposta, mas não há campo de corpo documentado para alterá-la aqui; gerencie a inscrição pela lista de events.

Requisição

Headers

Parâmetros de caminho

Corpo

Todos os campos são opcionais nesta operação: envie apenas o que deseja alterar. Os campos omitidos mantêm o valor atual.

Objeto authorization

Exemplo — trocar a URL e a lista de eventos

curl -X PUT "https://api.selectwin.io/v1/webhooks/endpoints/wbe_01hqzvabc" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: 7c2f9d4a-1e88-4a1b-9c6e-3f0a2b5d7e10" \
  -d '{
    "name": "Webhook MyDomain",
    "endpoint": "https://webhooks.mydomain.com/selectwin",
    "events": [
      "transaction.approved",
      "transaction.pending"
    ],
    "forceActivities": false,
    "authorization": {
      "type": "bearer",
      "value": "novo-token-secreto"
    },
    "metadata": {
      "team": "ops"
    }
  }'

Exemplo — atualização parcial (só a URL)

{
  "endpoint": "https://webhooks.mydomain.com/selectwin"
}

Resposta

200 OK com o objeto do endpoint já atualizado. Diferente do Create, a resposta do update não inclui o secret, e authorization.value vem mascarado.

{
  "id": "wbe_01hqzvabc",
  "name": "Webhook MyDomain",
  "endpoint": "https://webhooks.mydomain.com/selectwin",
  "enabled": true,
  "authorization": {
    "type": "bearer",
    "value": "sl_wh_***"
  },
  "events": [
    "transaction.approved",
    "transaction.pending"
  ],
  "shotsQty": 3068,
  "lastDeliveryAt": "2026-04-12T17:56:33.000Z",
  "metadata": {
    "team": "ops"
  },
  "updatedAt": "2026-04-12T17:56:33.000Z",
  "createdAt": "2025-01-26T20:18:05.000Z"
}

Campos da resposta

Erros

A resposta de erro segue o envelope padrão com error.code estável — trate sempre pelo code, nunca pela message. Veja Tratamento de Erros.

Consulte o Catálogo de Códigos de Erro para a lista completa.

Boas práticas

• Teste a nova URL antes de salvar. Confirme que ela responde 2xx rapidamente a um POST HTTPS, antes de apontar o endpoint para ela.
• Ao editar events, leia a lista atual primeiro (via read) e envie a lista completa desejada — lembre que events substitui, não mescla.
• Use X-Idempotency-Key para que um retry de rede não reaplique a mesma atualização.
• Não conte com o update para trocar o segredo. Se precisar de um segredo novo (suspeita de vazamento), recrie o endpoint via Delete + Create e atualize sua verificação de assinatura.
• Faça uma mudança por vez em produção e confira depois se as entregas continuam saudáveis: os contadores acumulados shotsQty/failedShotsQty vêm no Listar (data[]) e no read (GET .../{endpointId}); para inspecionar quais disparos individuais falharam, use o Analyze.
• Cuidado com forceActivities: true — ele ignora a lista de events e envia tudo, podendo gerar um volume muito maior de entregas do que o esperado.
• Mantenha metadata para auditoria, registrando, por exemplo, quem alterou e quando, do lado do seu sistema.

Veja também

• Visão geral de Webhook Endpoints
• Criar um Webhook Endpoint
• Listar Webhook Endpoints
• Excluir um Webhook Endpoint
• Analisar entregas de um Webhook Endpoint
• Verificando Assinaturas de Webhook
• Convenções da API · Idempotência · Autenticação