Catálogo de Eventos de Webhook

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

Disputa e chargeback que reabrem. Uma disputa encerrada a seu favor pode voltar, e um chargeback revertido pode ser cobrado de novo. Cada vez que isso acontece na mesma venda chega um transaction.dispute ou transaction.chargeback novo, com id próprio, e o mesmo vale para o receivable.dispute e o receivable.chargeback de cada recebível. A primeira disputa e o primeiro chargeback chegam como sempre chegaram. Já a vitória, que devolve a venda a approved, não gera um segundo transaction.approved, porque a aprovação é uma vez por venda: para saber o desfecho, leia a transação. Veja Uma vez por recurso × uma vez por ocorrência.

#Pagamento combinado (2 cartões ou cartão + Pix)

Num pedido pago com 2 cartões (dualcredit) ou cartão + Pix (creditpix), cada parte é uma transação com o bloco paymentGroup (id, method, status, legIndex, legCount, isPrimary, totalAmount e transactionIds — as transações atuais das partes do pedido, para ligar as cobranças). Uma parte só é anunciada como aprovada quando o pedido inteiro está pago, então não entregue nada por uma parte antes disso:

• Pedido pago: sai transaction.approved de cada parte, uma vez, junto com checkout.session.completed (que traz paymentGroupId e transactionIds[]). Depois disso, cada parte é como qualquer transação (estorno, contestação).
• Parte do Pix: sai transaction.pending (o QR) e, se o pedido não fechar, o fim dele (transaction.canceled ou transaction.failed).
• Dinheiro voltando (transaction.refunded, transaction.chargeback, transaction.dispute): sai sempre. Exemplo: o Pix pago depois de o pedido ter falhado é estornado automaticamente e chega só como transaction.refunded, nunca como transaction.approved.
• Não saem: a reserva do cartão (transaction.pre-authorized), a recusa ou o cancelamento de uma tentativa de cartão (o comprador troca de cartão na mesma página) e a aprovação de uma parte antes de o pedido estar pago.

#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 — veja Marketplace (sub-contas). O payload.object é a sub-conta (o objeto de conta), e id é o bus_… que você usa em onBehalfOf.

#Saques (Withdrawals)

#Webhooks

#Checkout

#Produtos

Um evento por variante. Uma operação que mexe em várias variantes de uma vez entrega o evento do produto e um variant.* para cada variante afetada, nunca um evento só para o lote. Criar um produto com 3 variantes entrega um product.created e 3 variant.created. Excluir o produto entrega um product.deleted e um variant.deleted por variante que saiu com ele. Quando a moderação retira o produto do ar, chegam um product.updated e um variant.updated para cada variante desligada. Quem sincroniza só variantes pode assinar só variant.*. Como a ordem de entrega não é garantida, um variant.created pode chegar antes do product.created do mesmo produto.

Nos eventos de criação e de atualização, payload.object é o produto (com as variantes) ou a variante, na mesma forma da leitura.

#Cupons

Cada alteração gera um evento: a que desativa o cupom é coupon.disabled, e as demais são coupon.updated. payload.object é o cupom na mesma forma de GET /v1/coupons/{couponId}, com resource: "coupon". O cupom que vence, esgota ou é excluído não gera evento.

#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).

#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.

#Cookies de rastreio (cookies) em checkout.session.*

Os identificadores do navegador do comprador chegam em payload.object.cookies, irmão de utm, com o nome do cookie como chave e o valor como veio — é o que o seu CAPI/Conversions API precisa para casar um carrinho abandonado com o anúncio:

{
  "type": "checkout.session.abandoned",
  "payload": {
    "object": {
      "object": "checkout.session",
      "id": "sess_a1b2c3d4e5f6789012ab",
      "utm": { "source": "meta", "medium": "cpc", "campaign": "lancamento" },
      "cookies": {
        "_fbp": "fb.1.1790000000000.1234567890",
        "_fbc": "fb.1.1790000000000.IwAR1x...",
        "_ga": "GA1.1.1234567890.1790000000",
        "_gcl_au": "1.1.1234567890.1790000000"
      }
    }
  }
}

• null quando nada foi capturado — o comprador saiu antes de a página rodar, ou não consentiu. Não é um objeto vazio.
• As chaves são as do navegador (_fbp, não fbp); cookies de GA4 com stream aparecem como _ga_<id do stream>.
• A sessão os acumula enquanto o comprador navega; um evento posterior (reactivated, expired) pode trazer mais chaves que o created.
• Na venda aprovada eles já chegavam em transaction.* como metadata.cookies; agora também chegam na sessão.

#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 (o prazo é 30 s, mas acima de 5 s o endpoint passa à fila agendada) 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.