Pular para conteúdo

Recadastrar o webhook da PIED

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-09-21

Sintoma

Pararam de chegar pedidos em tempo real. O watchdog registra no GlitchTip um erro do tipo "Webhook PIED silencioso há ~Nh úteis…" — ou alguém nota pedidos recentes que não apareceram no painel (só via poll, com atraso).

Causa

Quando a entrega em POST /webhook/pied falha, a PIED desativa o webhook e para de enviar. Ela não religa sozinha quando o servidor volta. É preciso excluir e recadastrar o webhook no dashboard da PIED.

Duas formas de falha já vistas em produção:

  • 404 — nossos servidores fora do ar (deploy, reinício, indisponibilidade);
  • timeout — o servidor está de pé e saudável, mas a rede oscila e a PIED não consegue entregar. Foi o caso de 18/09/2026: ~5 min de rede degradada (Read Timeout, depois Temporary failure in name resolution no log) derrubaram o webhook por 2h44, 33× a duração da falha. Container restarts=0 e jobs logando normalmente durante todo o silêncio — app de pé não descarta esta causa.

⚠️ A PIED não reenvia o que se perdeu. O recadastro restabelece o fluxo dali para a frente; os eventos do apagão estão perdidos e só voltam pelo poll REST (abaixo).

Conserto (dashboard da PIED — ação da Maxsul)

  1. Confirme que o servidor está de pé: GET https://pied.maxsul.xadm.biz/health responde {status: UP, ...}.
  2. No dashboard da PIED, vá em webhooks/integrações.
  3. Exclua o webhook do X-Adm (o que aponta para https://pied.maxsul.xadm.biz/webhook/pied).
  4. Recadastre com a mesma URL (POST para https://pied.maxsul.xadm.biz/webhook/pied) e, se houver, o mesmo segredo (X-Pied-Secret = PIED_WEBHOOK_SECRET).
  5. Dispare um evento de teste (ou aguarde o próximo pedido) e confira que chegou: painel / mostra o pedido, ou em /dados a tabela pied_webhook tem recebido_em recente.

Assim que um webhook novo chega, o watchdog fecha o episódio sozinho (o max(recebido_em) avança) e volta a vigiar — sem reset manual.

Prevenção / reduzir recorrência

  • Minimizar 404s: o deploy 50/50 (jar + native lado a lado) e o initialDelay dos jobs reduzem janela de indisponibilidade; ainda assim, todo reinício é uma janela em que a PIED pode ver 404.
  • Backstop: o poll REST (a cada 6h) recupera o dado que o webhook perdeu — não é tempo real, mas a normalização é idempotente pela chave code. ⚠️ Recuperar o dado não era o mesmo que entregar o pedido. Se o apagão engoliu o evento de pagamento, o poll traz o pedido já pago — e o gate, que é a transição para received, não tem transição a testemunhar: o pedido encalha em CAPTURADO, sem erro e sem alarme. Foi assim que quatro pedidos ficaram parados de sexta a segunda em 18/09/2026. A decisão 0023 fecha isso com o resgate da 1ª captura já paga (PIED_GATE_PRIMEIRA_CAPTURA_DESDE). Com o resgate desligado (default), confira o console depois de todo apagão: pedidos pagos na janela cega ficam em CAPTURADO esperando Enfileirar.
  • Vigia: mantenha PIED_WATCHDOG_HABILITADO=true em produção. O silêncio vira alerta por duas réguas — 45 min comerciais (seg–sex 8h–18h) e 24h úteis como rede de fora do horário. Ajuste por PIED_WATCHDOG_LIMITE_MIN_COMERCIAL / PIED_WATCHDOG_LIMITE_HORAS (ver Configuração).