Como webhooks com falha são retentados e os eventos chegam em ordem?

Seu receptor pode armazenar um evento mesmo quando o remetente nunca recebe a confirmação. Uma retentativa pode, portanto, repetir um trabalho que sua aplicação já aceitou.

Retentativas atrasam alguns eventos. Eventos mais recentes podem chegar antes que essas retentativas terminem. Armazene identificadores de eventos e horários de ocorrência para que essas entregas não sobrescrevam trabalho mais recente.

O que conta como uma entrega com falha?

Bird trata uma entrega como falha quando recebe uma resposta sem sucesso ou a solicitação expira.

Retorne HTTP 2xx após armazenar o evento para interromper as retentativas dessa entrega. Um redirecionamento, erro de cliente ou erro de servidor permanece elegível para retentativa.

Por exemplo, 400 registra uma solicitação rejeitada, mas não informa Bird para descartá-la. Use uma resposta de erro quando a verificação de assinatura ou o armazenamento durável falhar, para que a entrega possa ser recuperada.

Armazene o evento antes de confirmá-lo. Retornar sucesso primeiro pode perder o evento se a operação de armazenamento posterior falhar.

Mantenha o processamento lento em um worker em segundo plano para que seu receptor possa responder rapidamente. A função do receptor é verificar e preservar o evento antes que esse trabalho comece.

Qual é o cronograma de retentativas?

Bird usa sete intervalos de retentativa após a tentativa inicial, totalizando oito tentativas.

O cronograma dá aproximadamente 27,5 horas para você reparar um receptor antes que as tentativas automáticas terminem.

Bird ajusta aleatoriamente cada intervalo em até 20% para mais ou para menos, distribuindo as retentativas após uma indisponibilidade. Um intervalo de cinco minutos, portanto, varia de quatro a seis minutos antes de outros ajustes.

Uma resposta de limitação ou timeout pode alterar o próximo intervalo. Bird também considera Retry-After, um cabeçalho de resposta que solicita um atraso antes da próxima tentativa. Trate o cronograma como uma janela de recuperação, não como um prazo exato.

Cada retentativa mantém o webhook-id do evento, para que seu receptor possa reconhecer duplicatas.

O que acontece após a última retentativa?

As tentativas automáticas param para aquela entrega. Você pode solicitar replay das entregas que falharam.

Você solicita a reentrega com createWebhookReplay, ou pela página do endpoint no dashboard. O replay lê o log de tentativas de entrega e seleciona os eventos que falharam. Um evento Bird nunca tentado, como um que chegou enquanto o endpoint estava pausado, não tem tentativa para selecionar, então o replay não consegue recuperá-lo.

A resposta é 202, indicando que o replay foi enfileirado para execução em segundo plano. Ela não inclui uma contagem ou identificador de tarefa. Use listWebhookAttempts para inspecionar as tentativas subsequentes.

Cada reentrega usa uma única tentativa em vez do cronograma acima. Bird registra a tentativa e encerra o trabalho independentemente de o receptor ter aceitado ou não. Reenviar para um receptor que ainda está com problemas custa, portanto, uma requisição por evento em vez de oito. Corrija o receptor e depois solicite o reenvio novamente. Essas falhas não afetam a saúde do endpoint. Uma reentrega aceita limpa a degradação.

O replay ignora entregas já confirmadas com sucesso. Uma reentrega mantém seu webhook-id original, então seu tratamento de duplicatas continua valendo.

Defina since e until como strings de data e hora para delimitar a janela de recuperação. Ambos os limites são inclusivos. Ambos são comparados com o horário da tentativa de entrega, não com o horário em que o evento ocorreu. Omitir since inicia a janela 24 horas antes da solicitação, então uma interrupção mais antiga precisa de um horário de início explícito. Omitir until encerra a janela no horário da solicitação.

As tentativas são retidas por três dias, que é o limite de alcance do reenvio. Um since anterior amplia a janela sem recuperar nada mais antigo. Um único reenvio também cobre no máximo os 10.000 eventos mais antigos na janela, então uma interrupção longa exige várias janelas mais estreitas.

Uma organização pode solicitar 20 replays por dia UTC. Uma solicitação adicional recebe 429 com WebhookReplayQuotaExceeded, então combine a recuperação em uma janela em vez de solicitar replay por evento.

E se meu endpoint continuar falhando?

Bird marca um endpoint que está falhando como degradado. Ele pausa a entrega após cerca de cinco dias de falhas ininterruptas.

Você pode ler seu status como active, degraded ou paused. Um endpoint degradado continua recebendo entregas e tentativas. Uma entrega bem-sucedida limpa a degradação e reinicia o contador de falhas contínuas.

Um endpoint pausado para de receber eventos e não retoma automaticamente. Reative-o com updateWebhook, definindo status como active. Então faça replay da janela, que recupera as entregas que falharam antes da pausa. Reative primeiro: um replay solicitado enquanto o endpoint ainda está pausado retorna 202 e não reentrega nada. Os valores de status graváveis são active e paused.

Alterar a url de recebimento ou concluir uma entrega de teste bem-sucedida também limpa a degradação. A URL substituta deve ser publicamente acessível HTTPS, então endereços privados não podem restaurar a acessibilidade. URLs com mais de 2.048 caracteres falham na validação, então encurte uma URL gerada antes de enviá-la.

Editar a descrição do endpoint ou as assinaturas de eventos não demonstra que ele pode receber solicitações. Essas alterações mantêm a degradação, assim como uma entrega de teste que falhou.

Bird envia e-mail aos proprietários da organização quando um endpoint fica degradado. Nenhum outro e-mail de degradação é enviado até que o endpoint se recupere. Falhas repetidas, portanto, não produzem um e-mail para cada tentativa. Uma falha após a recuperação inicia outro período de degradação.

Existe uma fila de mensagens mortas?

Bird não fornece uma fila separada de eventos que falharam para você consultar. Inspecione as tentativas de entrega e solicite replay.

Corrija o receptor, reative-o se necessário e faça replay da janela afetada. Não há fila separada para drenar depois.

Os eventos chegam em ordem?

Os eventos podem chegar em uma ordem diferente daquela em que ocorreram.

Um evento email.delivered pode chegar antes do evento email.accepted da mesma mensagem. Compare os horários dos eventos em timestamp antes de aplicar uma alteração que sobrescreveria um estado mais recente.

Rastreie cada parte de uma cobrança SMS separadamente. Por exemplo, a taxa de entrega e uma taxa da operadora são componentes de custo distintos.

O objeto cost é null até que um componente tenha sido precificado. Seus valores de componente são strings decimais ou null. O campo amount é uma string decimal que soma os componentes presentes naquele payload.

Faça merge de cada componente usando o timestamp de evento mais recente. Substituir o objeto inteiro pode apagar um componente fornecido por outro evento, ou restaurar uma cobrança mais antiga.

Um componente null significa que ele não foi precificado naquele payload. Não significa uma cobrança de zero. Eventos SMS descreve esse merge em contexto, e webhooks cobre a semântica de entrega.