Reenviar entregas

Reenvie (redeliver) uma entrega de webhook específica ao endpoint exato que a recebeu, sem afetar as demais entregas do mesmo evento. É o recurso certo para reprocessar uma falha pontual depois de corrigir uma indisponibilidade temporária no seu servidor.

POST /v1/webhooks/dispatches/{dispatchId}

Um dispatch é o registro de uma tentativa de entrega de um evento de webhook a um endpoint de destino. Ele guarda o status (pending, retrying, success, failed), o número de tentativas e a última resposta HTTP do seu servidor. Quando uma entrega falha, este endpoint permite disparar uma nova tentativa reaproveitando o mesmo registro — direcionada apenas àquele endpoint.

Como funciona

Ao receber o dispatchId, a API:

1. Localiza o dispatch na sua conta, junto do evento e do endpoint associados.
2. Reconstrói o payload do evento (o mesmo conteúdo da entrega original).
3. Enfileira uma nova tentativa de entrega apenas para aquele endpoint.
4. Responde 200 com redispatched: true, confirmando que o reenvio foi disparado.

A confirmação 200 significa "aceitei reenviar", não "seu servidor recebeu". A entrega é assíncrona: o resultado real (sucesso ou nova falha) aparece depois no status e no responseStatusCode do dispatch. Para acompanhar, consulte a listagem e filtre pelo dispatch.

Quando usar

• Recuperar uma falha pontual: seu servidor ficou fora do ar e perdeu uma entrega; depois de normalizar, reenvie aquele dispatch específico.
• Reprocessar de forma direcionada: forçar a entrega a um único endpoint sem reenviar o evento aos demais.
• Diagnosticar: confirmar se uma falha é persistente ou transitória observando o resultado da nova tentativa.

Quando NÃO usar:

• Não use reenvio como substituto de polling. A Selectwin já reenvia automaticamente entregas falhas com backoff; o reenvio manual é para casos pontuais. Veja Por que não fazer polling.
• Se precisa que todos os endpoints recebam o evento de novo, use o reenvio de evento, não o de dispatch.

Requisição

Headers

Este endpoint não recebe corpo de requisição, portanto não envie Content-Type nem JSON. Como a operação é naturalmente idempotente (reenviar o mesmo dispatch tem o mesmo efeito), não há X-Idempotency-Key aqui.

Parâmetros de caminho

Exemplo

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

Resposta

Sucesso (200 OK)

{
  "id": "wdi_01hqzvabc",
  "eventId": "wbh_01hqzvabc",
  "endpointId": "wbe_01hqzvabc",
  "endpoint": "https://webhooks.mydomain.com/selectwin",
  "redispatched": true,
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": {
    "self": {
      "href": "https://api.selectwin.io/v1/webhooks/dispatches/wdi_01hqzvabc",
      "method": "POST",
      "description": "Redispatch webhook delivery attempt."
    },
    "list": {
      "href": "https://api.selectwin.io/v1/webhooks/dispatches",
      "method": "GET",
      "description": "List webhook dispatches."
    }
  }
}

Campos da resposta

Erros

A API usa o error.code como identificador estável da falha — trate por ele, nunca pela message. Veja a estrutura do envelope em Tratamento de Erros.

Exemplo de erro para um dispatchId malformado:

{
  "error": {
    "status": "Bad Request",
    "statusCode": 400,
    "category": "validation",
    "message": "Webhook dispatch ID is invalid",
    "details": "Webhook dispatch ID is invalid. Please check the dispatch ID and try again.",
    "code": "webhookDispatchIdInvalid",
    "resource": "webhook"
  }
}

Boas práticas

• Torne seu handler idempotente. Uma reentrega pode chegar depois da entrega original já processada. Deduplique pelo eventId (ou pelo ID do evento dentro do payload) e ignore eventos já tratados. Veja Chave de Idempotência para o conceito.
• Verifique a assinatura HMAC de toda entrega reenviada como faz com qualquer webhook — a reentrega não dispensa a validação de origem.
• Corrija a causa antes de reenviar. Reentregar enquanto seu endpoint ainda falha só consome tentativas; primeiro restabeleça a disponibilidade do servidor.
• Acompanhe o desfecho pela listagem, não por polling em loop. Filtre por endpoint ou status para ver se a nova tentativa virou success ou failed.
• Reenvie só o que precisa. Para recuperar muitas falhas, identifique-as primeiro na listagem (use onlyerrored=true) e reenvie dispatch a dispatch — em vez de reenviar o evento a todos os endpoints.
• Trate o 200 como "aceito", não "entregue". Não conclua que o consumidor recebeu o evento só porque o reenvio retornou 200.

Veja também

• Webhook Dispatches / Overview — o que é um dispatch, modelo do objeto e ciclo de vida.
• Webhook Dispatches / List — liste e filtre entregas para encontrar falhas e acompanhar resultados.
• Webhook Dispatches / Analytics — taxas de sucesso e falha das entregas.
• Webhook Events / Resend — reenvio de um evento a todos os endpoints elegíveis.
• Por que não fazer polling e Convenções da API.