workflows

Webhook ou consulta periódica: como escolher o gatilho da automação

Compare evento disponível, demora aceitável, limite de chamadas e necessidade de conciliação antes de escolher webhook, consulta ou combinação.

Antes de ligar um sistema a outro, decida como o fluxo descobrirá a mudança. Um webhook avisa sobre um evento; uma consulta periódica pergunta pelo estado. Uma combinação pode dar rapidez e uma conferência posterior, desde que o fornecedor permita e a equipe consiga operá-la.

Resposta curta

Use webhook quando o fornecedor oferece o evento necessário, há um destino seguro para recebê-lo e o atraso de uma varredura prejudicaria o processo. Use consulta periódica quando não existe evento adequado ou receptor seguro, inclusive o oferecido pela plataforma, e a demora é aceitável. Combine evento e leitura de reconciliação quando perder um aviso teria efeito material e a API permite uma conferência proporcional. O contrato do fornecedor prevalece sobre uma regra geral.

Matriz de decisão do gatilho

Pergunta sobre o processo Indicação Condição para liberar
O evento correto existe e precisa ser tratado logo? Webhook Autenticar origem, registrar ID e aceitar duplicatas sem repetir a ação
Não há evento adequado ou receptor seguro, inclusive gerenciado pela plataforma? Consulta periódica Respeitar limites, filtrar alterações e definir intervalo/latência aceitável
O aviso é rápido, mas pode falhar ou chegar sem estado final? Webhook + consulta de reconciliação Comparar por ID/estado e não executar duas vezes o mesmo efeito
Nenhum método permite verificar o estado com confiança? Não automatizar a ação crítica ainda Obter fonte de verdade e responsável humano

Ativo original da Pulse: anote mudança a detectar | evento disponível | atraso máximo tolerado | chamadas previstas | fonte do estado atual | como reconciliar | responsável. É uma ficha de decisão, não um teste de plataforma. Não guarde credenciais nela.

O receptor não precisa ser hospedado pela sua empresa: serviços de automação podem fornecer um endpoint gerenciado. Confirme na ferramenta antes de concluir que a única alternativa é consultar a API.

Um caso brasileiro sem regra universal

Uma pequena empresa acompanha a situação de uma cobrança no Asaas. A documentação do Asaas recomenda webhook para acompanhar mudanças e GET para consultar o estado atual; consultar repetidamente pode consumir limite de API e resultar em 429. Isso vale para essa integração. Outro provedor de cobrança pode ter eventos, prazos e requisitos diferentes. Para uma cobrança específica contestada, a consulta pontual do estado pode ser mais útil do que esperar outro evento.

A lógica de custo é simples: consultas programadas fazem chamadas mesmo quando nada mudou; webhooks exigem receptor, validação e tratamento de reenvio. Não há economia garantida sem medir frequência, limites e operação. Em plataformas de fluxo, chamadas e paginação podem consumir ações; Microsoft explica que a contagem depende do plano e do conector.

Reconciliação é uma decisão separada

A Shopify recomenda trabalhos de reconciliação porque a entrega de webhook nem sempre é garantida. O método combinado não significa consultar a API a cada segundo: defina janela de conferência, IDs e estado final conforme o risco. Se a consulta devolve páginas, confira a cobertura do lote antes de ações em massa.

Antes de ativar, teste com dados autorizados: evento válido, evento duplicado, ausência de evento e estado que mudou depois do aviso. Pare se não houver ID para deduplicar, se não for possível verificar origem ou se uma ação externa puder ser repetida sem controle. Veja como validar a origem do webhook, evitar ação duplicada e rastrear registros ausentes.

Fontes