Visão geral

Introdução

Os Webhook Endpoints permitem que você configure URLs em seu sistema para receber notificações em tempo real sobre eventos que ocorrem na API da SelectWin. Em vez de constantemente consultar a API para verificar atualizações, os webhooks enviam automaticamente dados para seu sistema assim que os eventos ocorrem.

Conceitos Fundamentais

• Webhook Endpoint: Uma URL (HTTPS) em seu sistema que receberá as notificações de eventos.
• Eventos: Ocorrências específicas no sistema da SelectWin, como a criação de uma transação ou uma mudança de status.
• Assinaturas de Eventos: A lista de tipos de eventos que você deseja receber no endpoint (campo events[]).
• Secret: Segredo de assinatura (whsec_...) retornado uma única vez na criação. Usado para verificar o cabeçalho X-Selectwin-Signature de cada entrega.

Autenticação

Todas as chamadas usam o cabeçalho SelectKey com sua chave de API (sk_test_ em sandbox, sk_live_ em produção). Base URL: https://api.selectwin.io/v1.

Estrutura do Webhook Endpoint (respostas da API)

Note os nomes endpoint (URL) e enabled (booleano) — não url/status:

• id (wbe_*; reads também aceitam endpoints legados wbh_*)
• name
• endpoint (URL HTTPS)
• enabled (boolean)
• events (array de strings | null)
• forceActive (boolean)
• shotsQty, failedShotsQty (integer)
• lastDeliveryAt (string ISO | null)
• metadata (objeto | null)
• createdAt, updatedAt (string ISO)
• merchant, _links (presentes em todas as respostas autenticadas)

Regras de respostas (fidelidade ao código):

• Create / rotate-secret: incluem secret (whsec_...) no root, retornado apenas uma vez.
• Read / Update / List: nunca retornam secret.
• As credenciais de autenticação no envio (headerAuthorization / headerAuthorizationType) são write-only — você as define na criação/atualização, mas elas não retornam em nenhuma resposta.
• Delete: { id, resource: "webhook", deleted: true, merchant, _links }.

Formato do Payload de Evento (enviado para seu endpoint)

Quando um evento ocorre, a SelectWin envia uma requisição POST para o endpoint configurado com um envelope JSON e o objeto do recurso em payload.object:

{
  "id": "wbh_123456789",
  "type": "transaction.approved",
  "source": "automatic",
  "payload": {
    "object": {
      "...": "o objeto completo do recurso (mesma forma da leitura do recurso)"
    }
  },
  "correlationId": null,
  "updatedAt": "2026-06-20T14:30:40.000Z",
  "createdAt": "2026-06-20T14:30:40.000Z"
}

O objeto do recurso fica em payload.object (não em data). Cada entrega é assinada — veja Verificando Assinaturas de Webhook.

Webhooks Acionados

A lista completa de eventos subscríveis está no Catálogo de Eventos.

Boas Práticas

1. Idempotência: Seu endpoint deve ser idempotente, capaz de receber o mesmo evento múltiplas vezes sem efeitos colaterais. Deduplique pelo id do evento (wbh_...).

2. Resposta Rápida: Responda com 2xx rapidamente (a entrega tem timeout de 30s); processe de forma assíncrona.

3. Verificação de Segurança: Valide o cabeçalho X-Selectwin-Signature (HMAC-SHA256) antes de processar o payload.

4. Use HTTPS: O campo endpoint exige uma URL https:// (URLs http:// são rejeitadas com 400).

5. Monitoramento: Use os Webhook Dispatches para auditar entregas e diagnosticar falhas por endpoint.

Recursos Disponíveis

Endpoints

O {webhookId} aceita o prefixo atual wbe_ e também endpoints legados wbh_.

Tipos de Eventos

A SelectWin suporta diversos tipos de eventos, agrupados por recurso (transação, recebível, assinatura, cliente, cartão, carteira, saque, vendedor, checkout e webhook). A lista completa e autoritativa está no Catálogo de Eventos de Webhook — apenas os valores listados lá são aceitos no campo events[].

Considerações de Segurança

1. Use HTTPS: Endpoints exigem HTTPS para proteger os dados em trânsito.

2. Verifique a assinatura: Valide X-Selectwin-Signature em toda requisição recebida.

3. Valide os Dados: Verifique sempre a estrutura e o conteúdo do payload recebido.

4. Nunca logue o secret (whsec_...): trate-o como uma senha.

5. Audite Eventos: Acompanhe os Webhook Dispatches para fins de auditoria.

Próximos Passos

• Leia sobre como Criar um Webhook Endpoint
• Aprenda a Listar seus Webhook Endpoints
• Saiba como Testar / Rotacionar o segredo de um Webhook Endpoint