Visão geral

Um dispatch (entrega) é o registro de uma tentativa de entregar um evento de webhook a um endpoint específico da sua conta. Cada dispatch guarda o resultado da tentativa — status, número de tentativas, código HTTP que o seu servidor devolveu e o corpo da resposta — para que você possa auditar entregas, diagnosticar falhas e reenviar uma entrega que não foi confirmada.

O que é um dispatch e por que ele existe

Quando algo acontece na sua conta (uma transação é aprovada, um reembolso é concluído, etc.), a Selectwin cria um evento de webhook — um registro imutável do fato. Esse evento precisa ser entregue aos seus servidores. Cada endpoint de webhook que você cadastrou e que assina aquele tipo de evento recebe a sua própria tentativa de entrega. Essa tentativa é o dispatch.

Em outras palavras:

• O evento responde "o que aconteceu" (e é o mesmo para todos os endpoints).
• O dispatch responde "como correu a entrega a este endpoint" (e é único por endpoint).

Os dispatches são o que você usa para responder perguntas operacionais do dia a dia: "Meu servidor recebeu o evento da transação X? Em quantas tentativas? Ele devolveu 200 ou 500? Posso reenviar?"

Modelo do objeto

Abaixo, um item de dispatch como aparece na listagem, anotado:

{
  "id": "wdi_01hqzvabc",                                  // ID opaco do dispatch (prefixo wdi_)
  "endpoint": "https://webhooks.mydomain.com/selectwin",  // URL de destino desta entrega
  "status": "success",                                    // resultado: pending | retrying | success | failed
  "event": "transaction.approved",                        // tipo do evento entregue
  "attempts": 1,                                          // quantas tentativas de entrega já houve
  "lastAttemptAt": "2026-04-12T17:56:33.000Z",            // quando a última tentativa ocorreu (ISO 8601 UTC)
  "responseStatusCode": 200,                              // status HTTP que o SEU servidor devolveu
  "responseBody": "OK",                                  // corpo (truncado) da resposta do seu servidor
  "successAt": "2026-04-12T17:56:33.050Z",               // quando a entrega foi confirmada (null se ainda não)
  "updatedAt": "2026-04-12T17:56:33.000Z",
  "createdAt": "2026-04-12T17:56:33.000Z"
}

Campos

Ciclo de vida (status)

Cada dispatch evolui por um destes estados. A Selectwin tenta entregar a entrega e aplica uma política de retentativas automáticas com backoff (espera crescente entre tentativas) quando o seu servidor não confirma o recebimento.

Como o servidor decide o resultado

• O dispatch entra em success quando o seu endpoint responde com um status 2xx dentro do tempo limite.
• Respostas 5xx, timeouts ou erros de rede colocam o dispatch em retrying; o attempts aumenta e o backoff espaça as próximas tentativas.
• Quando as tentativas automáticas se esgotam, o status vai para failed.
• A qualquer momento você pode forçar uma nova tentativa de uma entrega específica com o reenvio — útil depois que você corrigir uma indisponibilidade do seu lado.

Relação entre eventos e dispatches

Um único evento elegível para vários endpoints gera vários dispatches — um por endpoint:

webhookEvents (1) ──< (N) webhookDispatches
   evento "transaction.approved"  (id wbh_…)
   ├── dispatch → endpoint A  (id wdi_…, status: success, HTTP 200)
   └── dispatch → endpoint B  (id wdi_…, status: failed,  HTTP 500)

• A listagem de eventos já traz os dispatches aninhados em cada evento (dispatches[]), conveniente para uma visão "por evento".
• Os endpoints deste recurso expõem os dispatches como recurso de primeira classe — com filtros próprios (por status, endpoint, código HTTP, período) e reenvio individual — para uma visão "por entrega".

Operações

Todas as chamadas usam a base https://api.selectwin.io/v1 e autenticam pelo header SelectKey (nunca Authorization: Bearer/Basic):

curl https://api.selectwin.io/v1/webhooks/dispatches \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Em ambiente de sandbox, a chave começa com sl_test_. Veja Autenticação.

Identificadores

Os dispatches usam o prefixo de ID wdi_ (ex.: wdi_01hqzvabc). Trate o ID como string opaca — armazene a string inteira e não faça parsing dela. Os IDs relacionados que aparecem nas respostas seguem o mesmo padrão:

Erros

Os endpoints de dispatches retornam o envelope de erro padrão com um error.code estável (faça o tratamento pelo code, nunca pela message). Códigos relevantes:

Veja o envelope completo e a estratégia de tratamento no Catálogo de Códigos de Erro.

Boas práticas

• Monitore por exceção. Em vez de varrer todas as entregas, use o filtro onlyerrored=true na listagem para encontrar rapidamente o que falhou e precisa de atenção.
• Diagnostique pelo par responseStatusCode + responseBody. Eles mostram exatamente o que o seu servidor devolveu — é a forma mais direta de descobrir se a falha foi um 500 na sua aplicação, um timeout ou uma assinatura rejeitada.
• Reenvie só depois de corrigir. Use o reenvio para entregas failed após restaurar o seu endpoint; reenviar com o servidor ainda quebrado apenas repete a falha.
• Garanta idempotência no seu receptor. Como o mesmo evento pode ser tentado várias vezes (attempts > 1) e reenviado manualmente, o seu servidor deve tratar entregas repetidas do mesmo event/id sem efeito duplicado.
• Acompanhe a saúde com Analytics. Use o Analytics num período fixo para calcular a taxa de sucesso por endpoint e detectar degradação antes que vire incidente.
• Não use polling para o estado do negócio. Os dispatches servem para auditar a entrega; as mudanças de estado da sua conta chegam pelos próprios webhooks — veja Proibição de Polling.

Veja também

• Listar entregas — paginação e todos os filtros disponíveis.
• Analytics de entregas — métricas de sucesso/falha por período.
• Reenviar entrega — forçar nova tentativa de um dispatch.
• Webhook Events — Visão geral — o evento que origina os dispatches.
• Webhook Endpoints — Visão geral — os destinos das entregas.
• Verificando assinaturas de webhook — valide cada entrega que o seu servidor recebe.
• Convenções da API e Códigos de Erro.