Um webhook é uma notificação enviada por um sistema quando ocorre um acontecimento. Uma consulta periódica à API, ou polling, verifica de tempos a tempos se existem alterações. Os dois mecanismos podem ser usados na mesma integração.
Por isso, “webhooks ou API” é uma simplificação: os webhooks também podem fazer parte da API de um serviço. A decisão prática é como descobrir mudanças e como confirmar o estado que interessa ao negócio.
Exemplo: uma encomenda paga
Imagina uma loja que precisa de avisar o armazém depois de confirmar o pagamento. Com consultas periódicas, uma integração pergunta à loja por encomendas alteradas desde a última verificação. Com um webhook, a loja envia um aviso relacionado com a mudança.
A documentação do fornecedor determina o conteúdo do aviso, as garantias disponíveis e o procedimento de validação. Não assumes que todos os serviços enviam os mesmos campos ou repetem notificações da mesma forma.
No caso da Stripe, a documentação de webhooks descreve notificações de eventos, verificação de assinatura e aspetos como repetições e ordem de entrega. Estes detalhes são específicos da implementação.
Quando uma consulta periódica pode chegar
Se a operação aceita algum atraso e o serviço permite filtrar alterações, consultas periódicas podem ser uma solução adequada. Por exemplo, atualizar um relatório interno algumas vezes por dia pode não exigir reação imediata.
É preciso guardar o progresso e tratar paginação. Se a resposta contém apenas parte dos resultados, a integração não pode considerar o trabalho concluído depois da primeira página.
Define também o que acontece se uma execução falhar. Na execução seguinte, o sistema deve conseguir recuperar o intervalo em falta sem criar operações duplicadas.
Quando os avisos por evento ajudam
Webhooks são úteis quando queres reduzir o intervalo entre um acontecimento e a reação. Podem evitar verificações frequentes sem alterações, mas exigem um destino preparado para receber e validar notificações.
O aviso deve iniciar um fluxo controlado. Em muitos desenhos, a receção guarda o evento numa fila e o processamento acontece depois. A forma exata de responder e confirmar a receção deve seguir as regras do fornecedor.
O trabalho pesado não deve tornar o ponto de entrada instável. A equipa precisa de observar notificações recebidas, processadas e rejeitadas.
Quatro perguntas que evitam surpresas
Como sabemos quem enviou o aviso?
Segue o mecanismo de autenticação ou assinatura do serviço. Um endereço difícil de adivinhar não substitui a validação. Guarda segredos nos mecanismos apropriados e evita registá-los em mensagens de erro.
O mesmo evento pode chegar duas vezes?
Desenha o processamento para reconhecer repetições com uma referência persistente. Repetir a notificação não deve significar repetir um envio ao cliente ou uma operação de armazém.
Os eventos chegam sempre por ordem?
Não assumes essa garantia sem a confirmar. Um aviso atrasado não deve fazer uma encomenda voltar para um estado antigo. Pode ser necessário consultar o estado atual antes de agir.
Como detetamos o que ficou em falta?
Inclui reconciliação: uma comparação periódica entre os registos elegíveis na origem e os confirmados no destino. Isso ajuda a encontrar falhas que um painel de eventos “verdes” pode não mostrar.
Escolhe pelo requisito de negócio
Escreve o atraso máximo aceitável, o volume esperado e o efeito de uma repetição. Uma atualização de relatório e uma ordem de expedição têm riscos diferentes.
Depois, compara o suporte real de cada plataforma: eventos disponíveis, limites de consulta, filtros, histórico e possibilidade de reprocessamento. A visão geral de HTTP da MDN ajuda a compreender a base de comunicação, mas cada API exige leitura própria.
Se estás a ligar uma loja a sistemas de gestão, consulta também o planeamento da integração de faturação. Para desenhar uma ligação concreta, podes falar com a Letras Binárias, levando os eventos e as exceções que a operação precisa de suportar.
Recursos gratuitos
Se este artigo te foi útil, começa também pelos recursos gratuitos
É a forma mais simples de passar da leitura à experimentação: descarregas um recurso, testas no teu contexto e decides depois se queres aprofundar com o ebook.