Voltar ao blog
Blog
4 min

Webhooks ou consultas à API: como ligar dois sistemas

Webhooks avisam quando algo acontece; consultas periódicas procuram alterações. Aprende a escolher e a combinar os dois mecanismos numa integração fiável.

15 de novembro de 2026 • Por Jorge

Editorial

Tecnologia útil, explicada sem barulho

Artigos para quem quer perceber tecnologia com mais clareza, sem ruído e sem floreados desnecessários.

Recursos gratuitos

Queres começar antes de comprar?

Temos PDFs curtos e úteis para quem quer experimentar IA, escrever melhor e ganhar clareza sem entrar logo num produto pago.

Ver recursos Ver o ebook

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.

Blog

Mais artigos

Ecossistema de IA

Queres perceber melhor a IA e ao mesmo tempo aplicá-la no trabalho real?

Temos recursos gratuitos, ebooks práticos e trabalho direto com empresas em IA, agentes, automações e plataformas ajustadas ao negócio.

Olá! Precisas de ajuda?