Agenda de retentativas webhook

Receptores de webhook e workers de entrega precisam de uma lista explícita de tempos de espera antes de cada retentativa, não de uma promessa vaga de que o backoff será aplicado em algum ponto da pilha. Este montador de agenda de retentativas de entrega de webhook recebe um número máximo de retentativas, um atraso base estritamente positivo e uma estratégia fixa, linear ou exponencial, e devolve os atrasos por tentativa, as esperas acumuladas e uma fórmula curta que você pode fixar em testes ou exibir ao lado de um painel. A mesma lógica pura roda grátis no navegador e pela API, de modo que planejar uma escada exponencial de cinco retentativas offline coincide com o que o worker na borda usará ao configurar rotas de notificação ou loops de entrega próprios. Atrasos base inválidos falham de imediato com invalid_input em vez de inventar esperas nulas ou negativas que saturarariam uma fila.

O que é uma agenda de retentativas de webhook e como as três estratégias diferem

Sem uma agenda publicada, operadores não conseguem raciocinar sobre a latência de entrega no pior caso, e testes de carga não reproduzem os intervalos exatos que um worker de produção inserirá entre retentativas. O backoff fixo mantém o mesmo atraso base em cada tentativa: simples de entender e gentil com sistemas a jusante que só precisam de um breve resfriamento. O backoff linear multiplica o atraso base pelo índice da tentativa (base um), de modo que retentativas posteriores esperam proporcionalmente mais sem crescer tão rápido quanto a pura exponencial. Uma agenda de retentativas de entrega de webhook é a lista ordenada de atrasos que você espera antes da tentativa um, da dois e assim por diante após um POST falho na URL do assinante. Esta capacidade codifica três famílias comuns de backoff usadas em barramentos de mensagens e clientes HTTP. O backoff exponencial dobra o atraso anterior a cada vez usando base_delay vezes dois elevado a tentativa menos um, o padrão clássico para falhas de rede transitórias e limites de taxa. Você informa max_retries como quantas vagas de retentativa materializar, base_delay como semente positiva na unidade escolhida (em geral milissegundos) e strategy como fixed, linear ou exponential. A resposta ecoa essas entradas, lista os atrasos em ordem, soma-os como total_wait e expande um array schedule com número da tentativa, atraso e espera acumulada para que gráficos de UI e geradores de configuração não precisem de aritmética extra.

Contrato de entrada, formato da resposta e quando a validação falha

Envie por POST um corpo JSON com três campos obrigatórios. max_retries é um inteiro de um a cem que indica quantas retentativas agendar. base_delay é um número finito estritamente maior que zero em qualquer unidade coerente; zero e valores negativos são rejeitados porque uma espera não positiva ou faz busy-spin ou não faz sentido para o agendamento. strategy deve ser a string fixed, linear ou exponential (sem distinguir maiúsculas após o trim). Aliases como retries, base_ms e backoff são aceitos para que formatos de configuração existentes mapeiem de forma limpa. Campos ausentes, max_retries não inteiros, base_delay não finito e estratégias desconhecidas disparam invalid_input e não são cobrados. Em caso de sucesso o corpo inclui max_retries, base_delay, strategy, delays como array plano, total_wait como soma dos atrasos, attempt_count igual a max_retries, schedule como objetos com attempt, delay e cumulative, e formula reescrevendo a forma fechada da estratégia escolhida. Exemplo: max_retries cinco, base_delay mil, strategy exponential produz atrasos de mil, dois mil, quatro mil, oito mil e dezesseis mil com total_wait de trinta e um mil. Combine a agenda com sua própria política de jitter se precisar de dispersão aleatória; este endpoint omite de propósito o jitter e carimbos de relógio de parede para que os resultados permaneçam determinísticos entre navegador e API. O teto de max_retries é cem para que um erro de digitação não expanda um payload enorme nem estoure produtos intermediários em escadas exponenciais grandes.

Onde montar uma agenda de retentativas agrega valor em sistemas reais

Harnesses de teste de carga injetam o mesmo array de atrasos que o worker de produção usa, eliminando o clássico descompasso em que o staging retenta mais rápido que a produção e mascara bugs de limite de taxa. Plataformas de entrega que expõem ajustes de confiabilidade de webhooks podem chamar este montador quando um operador escolhe o máximo de retentativas e um modo de backoff, e então armazenar os atrasos resultantes ao lado do segredo do endpoint e da chave de assinatura. Runbooks de incidentes se beneficiam de um total_wait imprimível para que a equipe de plantão saiba quanto um assinante instável pode atrasar antes da última tentativa. Geradores OpenAPI e de SDK podem documentar escadas de exemplo concretas sem manter à mão tabelas que divergem do código em tempo de execução. Como a implementação é parse puro de nível A, cada chamada bem-sucedida custa o preço base publicado US$ 0,002 sem tokens de modelo nem rede de saída; validação falha não consome saldo. Mantenha base_delay e total_wait na mesma unidade das suas primitivas de sleep para nunca converter milissegundos em segundos por engano ao ligar a agenda em um loop de worker.