Criar um endpoint

Registre uma URL sua para receber webhooks — notificações HTTP que a Selectwin envia automaticamente quando algo acontece na sua conta (uma transação aprovada, um saque concluído etc.). Em vez de ficar perguntando à API "já mudou?" (polling), você cria um endpoint, escolhe os eventos que importam e a Selectwin avisa o seu sistema em tempo real.

POST /v1/webhooks/endpoints

Como funciona

Um webhook é o caminho inverso da API: em vez de você chamar a Selectwin, é a Selectwin que chama você. Você expõe uma URL HTTPS pública (o endpoint) e, sempre que ocorre um evento ao qual você se inscreveu, a Selectwin faz um POST para essa URL com o corpo do evento.

O fluxo de criação é direto:

1. Você envia o name, a URL (endpoint) e a lista de events que quer receber.
2. A Selectwin valida a URL e os tipos de evento, cria o recurso e devolve o objeto com um id (wbe_*).
3. Junto vem um secret (whsec_*) — exibido somente nesta resposta de criação. Guarde-o com segurança: é com ele que você verifica a assinatura de cada entrega para garantir que o POST recebido veio mesmo da Selectwin, e não de um impostor.
4. A partir daí, cada evento inscrito gera uma entrega (uma "tentativa de envio", contabilizada em shotsQty).

Seu endpoint precisa

• Aceitar requisições HTTP POST.
• Estar acessível publicamente e usar HTTPS (URLs http:// simples não são aceitas para entrega segura).
• Responder rápido (idealmente em poucos segundos) com um status 2xx. Faça apenas o mínimo no handler (enfileire e processe depois); lógica pesada inline causa timeout e re-tentativas.

Quando usar

• Você quer reagir a mudanças de estado (pagamento aprovado, recusado, estornado) sem polling. Esta é a forma recomendada — veja Proibição de Polling.
• Você tem um sistema (ERP, backoffice, fila) que precisa ser notificado de eventos da Selectwin.

Quando NÃO criar um novo: se já existe um endpoint para a mesma URL, a criação falha com webhookEndpointUrlExists. Para apenas mudar os eventos inscritos ou a URL de um endpoint existente, use Update em vez de criar outro.

Requisição

Headers

Nunca use Authorization: Bearer/Basic para autenticar na API Selectwin — a autenticação é sempre pelo header SelectKey. (O campo authorization do corpo, abaixo, é coisa diferente: são os headers que a Selectwin envia ao seu endpoint.)

Corpo

O objeto authorization (opcional) tem:

Exemplo

curl -X POST https://api.selectwin.io/v1/webhooks/endpoints \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: 9b1f2c3a-..." \
  -d '{
    "name": "My Production Webhook",
    "endpoint": "https://myapi.com/webhooks",
    "events": [
      "transaction.approved",
      "transaction.pending"
    ],
    "forceActivities": false,
    "authorization": {
      "type": "bearer",
      "value": "meu-token-secreto"
    },
    "metadata": {
      "team": "billing"
    }
  }'

Resposta

Sucesso (200 OK)

{
  "id": "wbe_01hqzvabc",
  "name": "My Production Webhook",
  "endpoint": "https://webhooks.mydomain.com/selectwin",
  "enabled": true,
  "authorization": {
    "type": "bearer",
    "value": "meu-token-secreto"
  },
  "events": [
    "transaction.approved",
    "transaction.pending"
  ],
  "secret": "whsec_abcdefghijklmnopqrstuvwxyz123456",
  "shotsQty": 0,
  "lastDeliveryAt": null,
  "metadata": {},
  "updatedAt": "2026-04-12T17:56:33.000Z",
  "createdAt": "2026-04-12T17:56:33.000Z"
}

Erros

Em caso de falha, o corpo segue o envelope padrão com error.code estável — trate sempre pelo code, nunca pela message. Veja Tratamento de Erros e o Catálogo de Códigos de Erro.

Boas práticas

1. Guarde o secret na hora. Ele só aparece aqui. Armazene-o em um secret manager e use-o para verificar a assinatura de cada entrega — veja Verificando Assinaturas.
2. Salve o id (wbe_*) retornado: você precisará dele para listar (List), atualizar (Update), remover (Delete) e ver as métricas de entrega (Analyze).
3. Use X-Idempotency-Key na criação para não acabar com dois endpoints idênticos se a requisição for repetida por timeout — veja Idempotência.
4. Inscreva-se no mínimo de eventos. Comece só com o que você realmente trata (ex.: transaction.approved) e expanda depois com Update; evite forceActivities: true a menos que precise mesmo de todos os eventos.
5. Responda rápido e processe assíncrono. Devolva 2xx imediatamente e jogue o processamento pesado para uma fila; handlers lentos viram timeout e re-tentativas.
6. Trate eventos como possivelmente duplicados. Re-tentativas podem reentregar o mesmo evento; torne seu handler idempotente (deduplique pelo id do evento).
7. Sempre HTTPS e URL pública. Endpoints internos ou sem TLS não recebem entregas seguras.
8. Monitore a saúde do endpoint via Analyze para detectar entregas falhando antes que virem perda de eventos.

Veja também

• Overview — o recurso Webhook Endpoints e seu ciclo de vida.
• List · Update · Delete · Analyze
• Verificando Assinaturas de Webhook — como validar o secret.
• Proibição de Polling · Convenções · Autenticação