Catálogo de eventos

Lista consolidada e autoritativa dos tipos de evento que a Selectwin pode entregar aos seus Webhook Endpoints. Ao criar/atualizar um endpoint, o campo events[] aceita exatamente os valores listados aqui — um valor fora desta lista é rejeitado com 400 na criação/atualização do endpoint.

Cada entrega traz o envelope do evento e o cabeçalho X-Selectwin-Signature — sempre verifique a assinatura (guia) antes de processar.

Transações

Clientes

Cartões

Assinaturas

Recebíveis

Carteiras

Vendedores (Sellers)

Primariamente para plataformas de marketplace, que recebem estes eventos para cada sub-conta via fan-out.

Saques (Withdrawals)

Webhooks

Checkout

Eventos de teste

Envelope do evento

O objeto do recurso é entregue em payload.object (não em data):

{
  "id": "wbh_01hqzvabc",
  "type": "transaction.approved",
  "source": "automatic",
  "payload": {
    "object": { "...": "objeto do recurso no momento do evento" }
  },
  "correlationId": null,
  "updatedAt": "2026-06-20T17:56:33.000Z",
  "createdAt": "2026-06-20T17:56:33.000Z"
}

• type — o tipo do evento (uma das linhas acima).
• source — origem do evento (automatic para eventos de plataforma; api para o ping de teste).
• payload.object — o objeto do recurso (mesma forma da leitura do recurso).
• correlationId — id de correlação da requisição originária, quando disponível.
• Em fan-out de marketplace, o envelope entregue ao parent inclui também account (publicId da sub-conta).

Nota: ao ler um evento pela API (GET /v1/webhooks/events), o objeto do recurso aparece no campo data da resposta da API — equivalente ao payload.object entregue ao seu endpoint.

Atribuição (utm) nos eventos

De onde veio a venda chega em payload.object.utm — no topo do objeto do recurso, irmão de metadata. Mesmo nome, mesmas chaves, nas duas famílias de evento:

{
  "type": "checkout.session.created",
  "payload": {
    "object": {
      "object": "checkout.session",
      "id": "sess_fc2b692056e12dc475b1",
      "status": "active",
      "utm": {
        "source": "instagram",
        "medium": "cpc",
        "campaign": "lancamento-agosto",
        "content": "criativo-v2",
        "term": "curso-online",
        "fbclid": "IwAR1x...",
        "gclid": "Cj0KCQ..."
      },
      "metadata": null
    }
  }
}

{
  "type": "transaction.approved",
  "payload": {
    "object": {
      "id": "tra_68qx2h3skshvd85g",
      "status": "approved",
      "utm": { "source": "instagram", "medium": "cpc", "campaign": "lancamento-agosto" }
    }
  }
}

Três regras que valem para os dois eventos:

1. utm é null quando não há campanha. Compra direta não vem com um objeto de chaves nulas — vem null. Trate null como "tráfego direto".
2. Chave ausente ≠ chave nula. Só aparece o que realmente veio: uma campanha sem term não traz a chave term.
3. Os nomes são curtos. A URL do anúncio usa utm_source, mas o que você recebe é source. A conversão é feita na entrada — você pode continuar mandando utm_source quando for você a criar a sessão ou a cobrança.

A sessão captura a atribuição uma vez, na primeira visita do comprador, e ela é imutável dali em diante — o clique que trouxe a venda não muda no meio do checkout. Quando a sessão vira cobrança, os cinco campos UTM descem para a transação sozinhos: o utm de transaction.* de uma venda de checkout é o mesmo da sessão, sem você fazer nada.

Boas práticas

• Assine a menor lista de eventos que você precisa — evita tráfego desnecessário.
• Deduplique pelo id do evento (wbh_...); reentregas podem repetir um evento.
• Responda 2xx rápido (≤ 30s) e processe de forma assíncrona — veja Proibição de Polling.
• A lista pode evoluir; novos tipos podem ser adicionados. Ignore com segurança tipos que você não trata.