Catálogo de eventos

Esta página é a referência dos tipos de evento que a Selectwin pode entregar aos seus webhook endpoints. Um evento é uma notificação gerada quando algo muda na plataforma (ex.: uma transação é aprovada). Cada tipo tem um nome no formato recurso.acao — por exemplo transaction.approved — e é exatamente esse nome que você assina no campo events[] ao criar um endpoint.

Use esta página como dicionário: descubra qual evento corresponde à mudança que você quer reagir, copie o nome literal e assine-o no seu endpoint. Os valores aqui são os únicos aceitos pelo contrato — qualquer string fora desta lista é rejeitada na validação (veja Erros).

Como a nomenclatura funciona

Todo tipo de evento segue o padrão recurso.estado (ou recurso.acao), tudo em minúsculas:

• O prefixo é o recurso afetado: transaction, customer, subscription, etc.
• O sufixo é o que aconteceu: normalmente o novo estado do recurso (approved, paid, canceled) ou a operação realizada (created, updated, deleted).

transaction . approved
└─ recurso ─┘ └─ estado ┘

O envelope do evento

Toda entrega chega ao seu endpoint como um POST com um corpo JSON (o envelope) e o cabeçalho de assinatura X-Selectwin-Signature. O envelope identifica qual evento ocorreu e carrega o recurso afetado no momento do evento:

{
  "id": "wbh_01hqzvabc",
  "type": "transaction.approved",
  "resource": "transaction",
  "resourceId": "tra_987654321",
  "createdAt": "2026-04-12T17:56:33.000Z",
  "data": {
    "id": "tra_987654321",
    "amount": 1500,
    "status": "approved"
  }
}

O envelope acima é o que chega ao seu servidor. Quando você lista eventos pela API (GET /v1/webhooks/events), cada item traz metadados adicionais de entrega — attempts, lastAttempt, dispatches[], etc. — e o payload entregue aparece como requestPayload. Veja Listar Eventos.

Ciclo de vida da entrega

Entender o ciclo ajuda a escolher os eventos certos e a tratar reentregas:

• A Selectwin aguarda sua resposta por até 15 segundos. Responda 2xx rápido e processe de forma assíncrona (fila). Veja Proibição de Polling.
• Falhas são reentregues com backoff. Como o mesmo evento pode chegar mais de uma vez, deduplique pelo id (wbh_...).
• Eventos que esgotam as retentativas automáticas podem ser reenviados manualmente — veja Reenviar Evento.

Catálogo completo por recurso

As tabelas abaixo listam todos os tipos de evento, agrupados pelo recurso. Os nomes na coluna Evento são os valores literais aceitos em events[].

Transações

Recebíveis

Assinaturas

Clientes

Cartões

Endereços

Carteiras

Saques (Withdrawals)

Webhooks

Como assinar eventos

Você escolhe quais eventos receber no campo events[] ao criar (ou atualizar) um webhook endpoint. O campo é um array das strings literais deste catálogo:

curl -X POST https://api.selectwin.io/v1/webhooks/endpoints \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Webhook MyDomain",
    "endpoint": "https://webhooks.mydomain.com/selectwin",
    "events": [
      "transaction.approved",
      "transaction.refused",
      "transaction.refunded"
    ]
  }'

Em sandbox, sua chave começa com sl_test_. Nunca use Authorization: Bearer/Basic — a Selectwin autentica via cabeçalho SelectKey. Veja Autenticação. O passo a passo completo da criação está em Criar Webhook Endpoint.

Consumindo e roteando eventos

No seu servidor, verifique a assinatura primeiro (ver Verificando Assinaturas) e então roteie pelo type. Deduplique pelo id e ignore tipos desconhecidos:

const seen = new Set(); // em produção, use um store persistente (Redis, DB)

app.post('/webhooks/selectwin', verifySignature, (req, res) => {
  const event = req.body; // já validado pela assinatura

  // 1) Idempotência: descarte reentregas do mesmo evento
  if (seen.has(event.id)) return res.status(200).send('ok (dup)');
  seen.add(event.id);

  // 2) Responda 2xx rápido; enfileire o trabalho pesado
  enqueue(event);
  res.status(200).send('ok');
});

function handle(event) {
  switch (event.type) {
    case 'transaction.approved':
      return fulfillOrder(event.resourceId, event.data); // amount em centavos
    case 'transaction.refused':
    case 'transaction.failed':
      return notifyPaymentProblem(event.resourceId);
    case 'transaction.refunded':
      return reverseFulfillment(event.resourceId);
    case 'subscription.canceled':
      return revokeAccess(event.data);
    default:
      return; // tipo não tratado — ignore com segurança
  }
}

Erros

Os erros abaixo aparecem ao registrar eventos inválidos em um endpoint (campo events[]). Trate sempre pelo error.code estável, nunca pela message — veja Tratamento de Erros e o Catálogo de Códigos de Erro.

Boas práticas

• Assine a menor lista de eventos que você precisa. Cada evento extra gera tráfego e ruído no seu endpoint.
• Deduplique pelo id (wbh_...). Reentregas e backoff podem repetir um evento; processe cada id uma única vez.
• Responda 2xx em ≤ 15s e processe de forma assíncrona (fila). Caso contrário, a entrega é cancelada e reagendada.
• Ignore tipos desconhecidos com segurança. O catálogo cresce; um default que não quebra mantém sua integração resiliente a novos eventos.
• Reaja ao estado, não infira. Use o evento de estado certo (ex.: transaction.approved para liberar o pedido, transaction.refunded para reverter) em vez de assumir transições.
• Verifique a assinatura antes de confiar no payload. Qualquer um que descubra sua URL pode forjar requisições — veja Verificando Assinaturas.
• Não faça parsing do nome do evento. Compare a string inteira; o ponto não é uma garantia de estrutura para sua lógica.

Veja também

• Webhook Events — Visão Geral — o recurso, o objeto e suas operações
• Listar Eventos — histórico de eventos entregues e seus dispatches
• Reenviar Evento — reenvio manual para diagnóstico/recuperação
• Verificando Assinaturas de Webhook — verificação HMAC obrigatória
• Criar Webhook Endpoint — onde você assina o events[]
• Proibição de Polling — por que usar webhooks
• Convenções da API — centavos, ISO 8601, IDs opacos