Webhooks — Entrega e falhas
O webhook da conta é entregue uma vez. Se a chamada falhar, ela não é repetida.
O que acontece quando falha
Seção intitulada “O que acontece quando falha”O app.smart faz um POST no seu endereço e espera até 5 segundos. Se o seu servidor demorar mais, recusar, cair ou não existir:
- O erro é registrado no nosso log
- O evento é descartado
Não há segunda tentativa, não há fila de falhas, não há tela para reenviar. E o seu lado não é avisado: para você, o evento simplesmente nunca chegou.
Como montar sabendo disso
Seção intitulada “Como montar sabendo disso”Responda rápido e processe depois. Receba, guarde numa fila sua e devolva 200 na hora. Todo trabalho pesado — consultar banco, chamar outro sistema, gerar arquivo — vai depois da resposta. Os 5 segundos são o limite, e um endpoint lento é a causa mais comum de evento perdido.
Não dependa do webhook como única fonte. Para o que não pode faltar, combine com uma leitura periódica pela API — o webhook avisa rápido, a leitura garante que nada ficou para trás.
Reconcilie depois de qualquer indisponibilidade. Subiu o servidor de volta? Busque pela API o que aconteceu naquela janela.
Seja idempotente. Mesmo sem reentrega automática, o seu endpoint precisa aguentar receber o mesmo evento duas vezes sem duplicar nada.
Quando a entrega não pode falhar
Seção intitulada “Quando a entrega não pode falhar”Duas alternativas melhores que o webhook da conta:
A ação de webhook dentro de um fluxo. Você vê cada execução, com o que foi enviado e o que voltou, e consegue reexecutar. Veja ações de workflow.
A consulta à API do seu lado. Em vez de esperar sermos nós a avisar, você pergunta de tempos em tempos. Menos imediato, e não perde nada.