Visão geral

Um Webhook Endpoint é uma URL do seu sistema que a Selectwin registra para entregar notificações automáticas (chamadas webhooks) sempre que algo acontece na sua conta — uma transação aprovada, um saque processado, e assim por diante. Em vez de você ficar consultando a API repetidamente para saber se algo mudou (polling), a Selectwin faz uma requisição POST para a sua URL no instante em que o evento ocorre. Esta página explica o que é o recurso, como ele funciona por baixo e quais operações existem para gerenciá-lo.

Um webhook (literalmente "gancho web") é uma notificação que um sistema envia a outro via HTTP assim que um fato relevante acontece. O endpoint é o "gancho" do seu lado que recebe essa chamada.

O papel do endpoint no produto

É útil separar três conceitos que andam juntos mas são recursos distintos na API:

Em palavras: você cria endpoints, a Selectwin gera eventos conforme sua conta opera, e para cada evento que casa com a inscrição de um endpoint ela faz um ou mais dispatches (tentativas de entrega) para aquela URL.

O modelo do objeto

Um endpoint de webhook é representado pelo objeto abaixo. Os campos vêm das respostas reais da API (create, read, update e list).

{
  "id": "wbe_01hqzvabc",                              // ID opaco do endpoint (prefixo wbe_)
  "name": "Webhook MyDomain",                         // nome de exibição que você escolhe
  "endpoint": "https://webhooks.mydomain.com/selectwin", // sua URL HTTPS que recebe os POSTs
  "enabled": true,                                    // o endpoint está ativo e recebendo eventos?
  "authorization": {                                  // cabeçalho de auth que a Selectwin envia ao seu servidor
    "type": "bearer",                                 // tipo do cabeçalho (ex.: "bearer", "basic")
    "value": "sl_wh_***"                              // valor — mascarado nas leituras
  },
  "events": [                                         // tipos de evento a que este endpoint está inscrito
    "transaction.approved",
    "transaction.pending"
  ],
  "shotsQty": 3068,                                   // total de tentativas de entrega já feitas
  "lastDeliveryAt": "2026-04-12T17:56:33.000Z",       // momento da última entrega (ISO 8601 UTC)
  "metadata": { "team": "ops" },                      // objeto livre seu, devolvido como veio
  "updatedAt": "2026-04-12T17:56:33.000Z",
  "createdAt": "2025-01-26T20:18:05.000Z"
}

Campos do objeto

Como funciona a entrega

Quando um fato relevante acontece na sua conta, a Selectwin avalia cada endpoint inscrito naquele tipo de evento e dispara a entrega:

Pontos importantes do mecanismo:

• Sempre por HTTP POST, com corpo JSON, para a endpoint configurada.
• Responda rápido com 2xx. Seu servidor deve confirmar o recebimento (200 ou 202) em poucos segundos e processar o conteúdo de forma assíncrona. Respostas lentas ou fora da faixa 2xx são tratadas como falha e geram nova tentativa.
• Reentrega com backoff. Falhas temporárias são repetidas automaticamente; cada tentativa conta em shotsQty/failedShotsQty. Falhas persistentes podem levar a Selectwin a marcar o endpoint como enabled: false.
• Inscrição por tipo. O endpoint só recebe os tipos listados em events. Para receber tudo independentemente da inscrição, há a flag forceActivities no create/update.

Ciclo de vida do endpoint

Idempotência do seu lado

Como há reentregas, o mesmo evento pode chegar mais de uma vez ao seu endpoint. Torne o seu processamento idempotente: identifique o evento pelo id (prefixo wbh_) do payload e ignore os que já foram processados. Isso evita efeitos colaterais duplicados (ex.: dar baixa duas vezes no mesmo pedido).

Autorização de saída do seu endpoint

O campo authorization configura um cabeçalho que a Selectwin envia ao chamar a sua URL — é como o seu servidor reconhece que a chamada veio da Selectwin (não é a sua SelectKey, que serve para você chamar a API).

• authorization.type — tipo do cabeçalho (ex.: "bearer", "basic").
• authorization.value — o valor; nas leituras vem mascarado (sl_wh_***).

Operações disponíveis

Todas as chamadas usam a base https://api.selectwin.io/v1 e exigem o cabeçalho de autenticação SelectKey (veja Autenticação).

O parâmetro de caminho é endpointId (ex.: wbe_01hqzvabc). As respostas de lista, delete e analytics incluem merchant e _links (HATEOAS); as respostas de single (create/read/update) trazem só o objeto do endpoint.

Erros

A tabela abaixo lista os error.code específicos deste recurso. Trate sempre pelo error.code (estável), nunca pela message. Para o envelope de erro e os códigos transversais (401, 403, 422, 429, 500), veja o Catálogo de Códigos de Erro.

Boas práticas

1. Use HTTPS sempre. A endpoint precisa ser uma URL pública e segura; dados de eventos trafegam por ela.
2. Responda 2xx em segundos e processe depois. Confirme o recebimento rápido e empurre o trabalho pesado para uma fila/processamento assíncrono, evitando timeouts e reentregas.
3. Seja idempotente. Deduplica eventos pelo id (wbh_) do payload, já que reentregas são esperadas.
4. Verifique a autenticidade. Cheque o cabeçalho de authorization e, melhor ainda, valide a assinatura com o secret — veja Verificando Assinaturas.
5. Guarde o secret na criação. Ele só vem na resposta do create; não há como recuperá-lo depois.
6. Inscreva-se só no que precisa. Comece com poucos tipos em events e expanda conforme a necessidade, para reduzir tráfego e ruído.
7. Monitore a saúde. Acompanhe shotsQty/failedShotsQty e use a página de Analyze para detectar entregas falhando antes que o endpoint seja desativado.
8. Salve o id (wbe_). Você vai precisar dele para atualizar, consultar, excluir e ver analytics.

Veja também

• Create — registrar um novo endpoint
• List — listar e filtrar endpoints
• Update — alterar URL, eventos e autorização
• Delete — remover um endpoint
• Analyze — estatísticas de entrega de um endpoint
• Webhook Events — os eventos entregues e o catálogo de tipos
• Webhook Dispatches — tentativas individuais de entrega
• Verificando Assinaturas de Webhook — validar a origem com o secret
• Convenções da API · Proibição de Polling · Catálogo de Códigos de Erro