0026 — Alerta de webhook parado também por e-mail, com aviso de volta¶
Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-09-30 · Decidido em: 2026-09-30
Contexto¶
O watchdog (0016, 0023)
detecta o webhook calado e registra um ERROR, que vai ao GlitchTip. Mas o conserto — excluir e
recadastrar o webhook no painel da PIED — é da Maxsul, e a Maxsul não olha o GlitchTip. No apagão
de 29–30/09/2026 o alerta saiu às 08:47 e só chegou a quem age por outro caminho.
Os destinatários da tela /destinatarios já recebem por e-mail os alertas que pedem ação da Maxsul
(erro terminal, 0005; cancelamento pós-import,
0010).
Decisão¶
O mesmo episódio que gera o ERROR do watchdog passa a gerar dois e-mails aos destinatários:
- "Webhook parado" — no mesmo momento do alerta (a régua que estourar primeiro), 1 por episódio. Traz desde quando está calado, a causa provável, o passo a passo do recadastro com a URL e o aviso de que os pedidos pagos seguem chegando pela contingência (0025).
- "Webhook voltou" — quando um webhook novo chega depois de um episódio alertado, 1 por episódio.
Fecha o ciclo para quem recadastrou: não precisa abrir
/dadospara saber se funcionou.
A volta é detectada pelo próprio watchdog: estado alertado (pied_watchdog_estado) com
max(recebido_em) mais novo que o do episódio. Um UPDATE condicional (encerrarEpisodio) desmarca
o episódio — só uma instância vence, então só uma manda o e-mail.
A volta só vira e-mail se for recente (até 1h). No primeiro deploy, o estado pode estar marcado de um apagão já resolvido (o de 29/09 está); ele é encerrado em silêncio, sem mandar "voltou" dias depois.
Mesma política de envio dos outros alertas: best-effort, desligado por PIED_ALERTA_HABILITADO, no-op
sem destinatários ou sem chave do Resend.
Consequências¶
- Quem pode consertar fica sabendo em até 45 min comerciais, com as instruções no próprio e-mail.
- Dois e-mails por apagão. Setembro teve dois apagões: ruído desprezível.
- O e-mail de volta diz que o webhook funciona, não que nada se perdeu: a PIED não reenvia os eventos do período. O texto diz isso.
- Sem destinatários cadastrados, nada muda em relação a antes (só o GlitchTip).
Alternativas consideradas¶
- Só o e-mail de parado: quem recadastra fica sem confirmação e precisa conferir à mão. Rejeitado pelo dono em favor do aviso de volta.
- Lista de destinatários separada para o webhook: hoje quem recebe os alertas é quem opera a PIED; separar seria configuração sem demanda.