Reenviar eventos

Reenviar um evento dispara uma nova tentativa de entrega de um evento de webhook que já foi gerado, usando o id do evento. É a forma manual de recuperar uma notificação que não chegou ao seu sistema — por falha de rede, indisponibilidade do seu endpoint ou um bug que você já corrigiu — sem precisar refazer a operação de negócio que originou o evento.

POST /v1/webhooks/events/{eventId}

Como funciona

Um webhook é uma notificação que a Selectwin envia para uma URL sua (o endpoint) quando algo acontece na sua conta — por exemplo, uma transação é aprovada. Cada notificação gerada é registrada como um evento de webhook (prefixo de ID wbh_), e cada tentativa de entrega desse evento a um endpoint é uma entrega (dispatch, prefixo wdi_). Um único evento pode ter várias entregas, uma para cada endpoint inscrito naquele tipo de evento.

Quando uma entrega falha (timeout, erro de conexão, ou seu servidor responde com status diferente de 2xx), a Selectwin já reagenda novas tentativas automaticamente, com backoff (intervalos crescentes). O reenvio manual deste endpoint existe para os casos em que o reagendamento automático não basta: o evento ficou marcado como failed, ou você corrigiu seu endpoint depois que as tentativas automáticas se esgotaram, ou simplesmente quer reentregar um evento já delivered para revalidar uma integração.

O fluxo de uma chamada de reenvio é assim:

Pontos importantes do mecanismo:

• A resposta é um aceite, não uma confirmação de entrega. O 200 OK com "sended": true significa "a Selectwin aceitou enfileirar o reenvio". A entrega ao seu endpoint acontece de forma assíncrona, logo depois. Para saber se a reentrega chegou, consulte a entrega (dispatches[]) do evento via List.
• O payload reenviado é o mesmo do original. O conteúdo do evento não muda; ele carrega os mesmos dados e é assinado da mesma forma. Por isso, continue verificando a assinatura de toda entrega — inclusive das reenviadas — conforme Verificando Assinaturas.
• Reenvio gera duplicidade por desenho. Seu endpoint deve ser idempotente: processar o mesmo evento duas vezes não pode cobrar de novo, enviar e-mail de novo, etc. Use o id do evento como chave de deduplicação. Veja a página de Visão Geral para o padrão recomendado.

Quando usar

• O endpoint estava fora do ar / respondendo erro e as tentativas automáticas se esgotaram; você quer recuperar o evento depois de corrigir.
• Você precisa ressincronizar um sistema externo após uma manutenção e quer reentregar eventos específicos.
• Você está testando a sua integração e quer disparar de novo um evento real conhecido para validar o processamento.

Quando não usar:

• Não use reenvio como substituto de polling. Construa sua lógica para reagir aos webhooks que chegam; o reenvio é uma ferramenta de recuperação pontual, não um mecanismo de sincronização contínua. Veja Proibição de Polling.
• Não reenvie em massa para "garantir". Como o seu endpoint é idempotente, reenvios desnecessários só geram trabalho repetido. Reenvie o evento certo, identificado pelo id.

Requisição

Headers

Este endpoint não tem corpo de requisição, então não é necessário Content-Type. O próprio reenvio é a ação; toda a informação vai no eventId da URL.

Parâmetros de caminho

Exemplo curl

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

Resposta

200 OK — o reenvio foi aceito e enfileirado.

{
  "id": "wbh_01hqzvabc",
  "sended": true,
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": {
    "self": {
      "href": "https://api.selectwin.io/v1/webhooks/events/wbh_01hqzvabc",
      "method": "POST",
      "description": "Resend webhook event."
    },
    "list": {
      "href": "https://api.selectwin.io/v1/webhooks/events",
      "method": "GET",
      "description": "List all webhook events."
    }
  }
}

Erros

A resposta de erro segue o envelope padrão com error.code estável — trate sempre pelo code, nunca pela message. Veja Tratamento de Erros e o Catálogo de Códigos de Erro.

Boas práticas

• Confirme a entrega depois do aceite. Após o 200, consulte o evento em List e verifique a última entrega em dispatches[] (status, responseStatusCode). Não trate "sended": true como prova de que o seu servidor recebeu.
• Garanta idempotência no seu endpoint. Deduplicar pelo id do evento é obrigatório: reenviar é, por definição, entregar o mesmo evento de novo. Guarde os IDs já processados e ignore repetições.
• Verifique a assinatura também nas reentregas. Toda entrega — original ou reenviada — vem assinada. Valide o HMAC antes de confiar no conteúdo; veja Verificando Assinaturas.
• Corrija a causa antes de reenviar. Se o endpoint estava devolvendo erro, conserte-o e confirme que responde 2xx antes de disparar o reenvio — senão a reentrega também falhará.
• Reenvie de forma direcionada. Identifique o evento exato pela List (filtre por status=failed, type, resourceid ou intervalo de datas) em vez de reenviar lotes inteiros.
• Respeite o backoff em 429/5xx. Em erros transitórios, espere antes de repetir; use error.retryAfterMinutes quando presente.

Veja também

• Visão Geral — o modelo do evento, estados de entrega e o padrão de consumo idempotente.
• List — encontre o eventId e acompanhe o resultado das entregas (dispatches[]).
• Catálogo de Eventos — todos os tipos de evento (transaction.approved, etc.).
• Verificando Assinaturas — valide o HMAC de cada entrega, inclusive reenvios.
• Proibição de Polling — por que reagir a webhooks em vez de consultar em loop.
• Convenções da API — IDs opacos, datas ISO 8601 UTC, dinheiro em centavos.