Retentativas e replay

O que a BlendFi faz quando o seu endpoint não está acessível, o que o seu endpoint pode retornar para controlar o comportamento de retentativa e como recuperar entregas que falharam.

O cronograma de retentativas

Linear, cerca de 30 segundos entre tentativas. Não é exponencial.

Timeout HTTP por tentativa: 5 segundos. Acima disso, a tentativa é tratada como falha de rede e conta como retentativa.

Depois de 5 tentativas, a mensagem de entrega vai para uma fila de mensagens com falha (DLQ) dentro da BlendFi. A linha org_webhook_deliveries correspondente permanece com status dispatched, peculiaridade operacional na v1; visível ao parceiro via GET /v1/webhook_deliveries/{id}.

O que a sua resposta controla

Como a BlendFi trata cada status HTTP que o seu endpoint retorna:

O erro mais comum: retornar não-2xx para uma duplicata. A BlendFi vai continuar retentando. Sempre retorne 2xx para duplicatas (use X-Blendfi-Event-Id como chave de controle de duplicatas); só falhe para erros genuínos de processamento.

Janela de replay (lado servidor)

Independente do cronograma de retentativas. Toda entrega assinada carrega um X-Blendfi-Timestamp; a BlendFi trata entregas com timestamp mais antigo que 300 segundos no momento do recebimento como tentativas de replay e rejeita. Esse limite é aplicado no seu verificador (veja Verificação de assinatura), a BlendFi não faz replay de payloads antigos, mas um atacante com assinatura vazada pode tentar.

Implicação prática: se o seu endpoint cair por mais de 5 minutos e a última retentativa da BlendFi esgotar, a entrega original some da janela de assinatura viva. Você ainda pode recuperar fazendo a reentrega manual do evento (que produz timestamp e assinatura novos), veja abaixo.

Reentrega manual

Quando uma entrega esgota retentativas (ou você só quer reprocessar por qualquer motivo), faça a reentrega:

curl -X POST $BLENDFI_BASE/v1/webhook_deliveries/del_01J.../redeliver \
  -H "Authorization: Bearer $BLENDFI_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Isso cria uma nova linha de entrega apontando para o evento original. Timestamp novo, assinatura nova, orçamento de retentativa novo. O ID do evento original permanece o mesmo, a sua chave de controle de duplicatas ainda funciona, então uma reentrega bem-sucedida deve ser um replay sem efeito do seu lado.

O dashboard de entregas:

curl $BLENDFI_BASE/v1/webhook_endpoints/we_01J.../deliveries \
  -H "Authorization: Bearer $BLENDFI_KEY"

Mostra o status de toda entrega recente, succeeded, failed, dispatched, com a última mensagem de erro. Útil quando um parceiro pergunta "a BlendFi tentou nos alcançar nesse horário?"

Procedimento de recuperação (indisponibilidade → reprocessar)

O que fazer depois de uma indisponibilidade de várias horas no seu endpoint:

1. Confirme que o endpoint voltou. Faça curl no seu URL /blendfi-webhooks com um payload sintético + assinatura válida, verifique se o seu caminho de código está saudável.
2. Liste as entregas falhas. GET /v1/webhook_endpoints/{id}/deliveries?status=failed, o filtro por intervalo temporal é seu amigo.
3. Reconcilie contra o seu estado local. Para cada entrega falha, decida se você realmente perdeu o evento ou se outros caminhos (polling, UI manual) pegaram.
4. Reentregue as que você perdeu. POST /v1/webhook_deliveries/{id}/redeliver por entrega. Idempotency-Key por chamada.
5. Acompanhe o dashboard de entregas. Confirme que cada reentrega tem sucesso.

Para janelas muito grandes (milhares de entregas perdidas), reconcilie via GET /v1/conversions e GET /v1/users primeiro, o seu estado local mais uma consulta ao estado canônico costuma resolver mais rápido que reentrega por evento.

Leia em seguida

• Verificação de assinatura, o caminho de código do verificador
• Gerenciamento de endpoints, pause um endpoint de forma limpa durante downtime planejado
• Catálogo de erros, webhook_delivery_not_found, invalid_webhook_delivery_state