Para acompanhar pagamentos, webhooks geralmente são mais eficientes para receber mudanças de status em tempo real, enquanto consultas à API são importantes para verificar o estado atual de uma operação e recuperar informações quando necessário. Em uma arquitetura robusta, os dois mecanismos podem ser complementares: o webhook avisa que algo aconteceu e a API permite confirmar ou recuperar o estado da transação.
A diferença parece técnica, mas produz consequências operacionais.
Se uma empresa precisa saber quando 100 mil pagamentos foram liquidados, consultar continuamente o banco para descobrir se cada um mudou de status cria um fluxo muito diferente de receber uma notificação apenas quando algo acontece.
Por isso, a escolha entre webhook e polling se torna mais relevante à medida que o volume aumenta.
O que é polling?
Polling é uma estratégia na qual um sistema consulta outro repetidamente para verificar se existe alguma atualização.
Imagine um ERP aguardando a confirmação de um pagamento.
A cada determinado intervalo, ele pergunta à API:
“Qual é o status desse pagamento?”
Se continuar pendente, espera e consulta novamente.
Quando o status muda para pago, o sistema atualiza seu registro.
O modelo é simples e pode funcionar bem em determinadas situações.
O problema aparece quando ele precisa ser repetido para um grande número de operações.
O que é webhook?
Webhook inverte essa lógica.
Em vez de o ERP perguntar continuamente se alguma coisa aconteceu, o fornecedor envia uma notificação quando existe uma mudança relevante.
O fluxo passa a ser:
pagamento → mudança de status → webhook → ERP
Se um pagamento for liquidado, rejeitado, cancelado ou devolvido, por exemplo, um evento pode ser enviado ao endpoint configurado pela empresa.
O sistema recebe a informação e executa a ação correspondente.
Qual é a principal diferença entre webhook e polling?
A diferença está em quem inicia a comunicação.
No polling:
seu sistema pergunta.
No webhook:
o outro sistema avisa.
Imagine 100 mil pagamentos aguardando alguma mudança.
Com polling, a aplicação pode precisar realizar consultas repetidas mesmo quando nada aconteceu.
Com webhook, as mensagens são enviadas quando existe um evento.
Isso tende a reduzir consultas desnecessárias e permite que o sistema reaja mais rapidamente às mudanças.
Webhook é sempre melhor que polling?
Não.
Webhook resolve muito bem o problema de receber eventos.
Polling ou consultas diretas resolvem bem outro problema: descobrir qual é o estado atual de um recurso.
Essa diferença é importante.
Imagine que o sistema não tenha recebido determinado webhook.
Se depender exclusivamente daquele evento, pode continuar acreditando que o pagamento está pendente.
Uma consulta à API permite perguntar:
“Qual é o estado atual desse pagamento?”
Por isso, arquiteturas robustas frequentemente combinam os dois modelos.
Como webhook e API podem trabalhar juntos?
Um desenho possível é:
1. O ERP cria o pagamento pela API.
2. O banco processa a operação.
3. Quando o status muda, envia um webhook.
4. O ERP recebe o evento.
5. Se necessário, consulta o recurso pela API.
6. O sistema atualiza o estado interno.
Além disso, uma rotina periódica pode procurar operações que permaneceram tempo demais sem atualização.
Nesse caso, a consulta funciona como mecanismo de recuperação.
O webhook é o caminho principal.
A consulta é uma camada adicional de consistência.
Por que polling pode gerar muitas chamadas?
Porque a aplicação consulta mesmo quando não existe novidade.
Imagine:
100 mil pagamentos pendentes;
uma consulta a cada minuto;
durante uma hora.
No cenário teórico em que todos permanecessem sendo consultados durante todo o período, seriam:
100.000 × 60 = 6 milhões de consultas
Isso não significa que qualquer implementação de polling necessariamente produzirá esse volume. Intervalos podem ser ajustados, operações concluídas podem sair da rotina e diferentes estratégias podem reduzir chamadas.
O exemplo serve para mostrar como o custo técnico cresce quando número de recursos × frequência de consulta aumenta.
Com webhooks, a lógica é orientada aos eventos efetivamente ocorridos.
Por que isso importa em um sistema financeiro cada vez mais conectado?
APIs já operam em escala muito alta no sistema financeiro brasileiro.
Em janeiro de 2025, o Open Finance registrava mais de 2,3 bilhões de comunicações bem-sucedidas por semana, segundo a Febraban.
Um ano antes eram mais de 1 bilhão por semana.
No período, o número de consentimentos passou de 43 milhões para 62 milhões, crescimento de 44%.
Open Finance não é equivalente às APIs proprietárias utilizadas para pagamentos empresariais, mas os números ajudam a mostrar a dimensão que a comunicação máquina a máquina já alcançou no sistema financeiro.
Quando sistemas conversam bilhões de vezes, eficiência de comunicação deixa de ser um detalhe de implementação.
Para quais eventos financeiros webhooks são úteis?
Webhooks podem ser utilizados para comunicar diferentes mudanças.
Por exemplo:
- Pix recebido;
- boleto pago;
- pagamento liquidado;
- pagamento rejeitado;
- transferência devolvida;
- cobrança vencida;
- estorno;
- mudança em uma transação de cartão.
Imagine uma cobrança.
O ERP cria o registro e passa a aguardar.
Quando o cliente paga, o evento chega.
O sistema identifica a cobrança correspondente e realiza a baixa.
Esse modelo permite aproximar conciliação do momento em que a movimentação acontece.
LEIA MAIS:
Pix via API: como integrar pagamentos e recebimentos na sua empresa
Cartão Corporativo com controles de gastos: como parametrizar limites por MCC, centros de custo e webhooks
ERP: o que é e quais os benefícios de integrá-lo com a API da Stark Bank
O que acontece quando um webhook falha?
Essa é a principal razão pela qual webhooks não deveriam ser tratados como mensagens infalíveis.
O endpoint da empresa pode estar indisponível.
Pode existir uma falha de rede.
A aplicação pode receber o evento e apresentar erro antes de processá-lo.
Por isso, é importante entender como o fornecedor lida com falhas de entrega.
Pergunte:
- existem novas tentativas?
- em quais intervalos?
- por quanto tempo?
- o evento fica disponível posteriormente?
- existe um ID único?
- consigo consultar eventos não processados?
A resposta determina a capacidade da integração de se recuperar.
Webhooks podem chegar duplicados?
Sim.
Uma aplicação deveria estar preparada para receber o mesmo evento mais de uma vez.
Isso pode acontecer, por exemplo, quando o fornecedor não recebe a confirmação de que a primeira entrega foi processada.
Por isso, eventos precisam possuir identificadores que permitam reconhecer duplicidades.
Se o evento 12345 já foi processado, recebê-lo novamente não deveria gerar a mesma consequência financeira duas vezes.
Essa é uma aplicação prática do conceito de idempotência.
Webhooks sempre chegam na ordem correta?
Uma arquitetura robusta também não deveria depender disso.
Imagine dois eventos:
A: pagamento processado
B: pagamento devolvido
Problemas de rede ou retries podem fazer com que as notificações sejam recebidas em uma sequência diferente daquela em que os eventos aconteceram.
Por isso, em vez de assumir que a última mensagem recebida representa necessariamente o estado correto, o sistema pode consultar o recurso e verificar seu estado atual quando houver dúvida.
Esse é outro exemplo de como webhooks e consultas à API se complementam.
Como funciona no Stark Bank?
O Stark Bank utiliza webhooks para comunicar mudanças nos recursos integrados pela API.
A documentação atual informa que é possível receber alterações de status de eventos como operações creditadas, falhas e reembolsos conforme acontecem.
A API também permite consultar os recursos e transações diretamente.
Outro recurso importante é a prevenção de duplicidades: endpoints de escrita aceitam identificadores externos, permitindo repetir uma requisição sem criar novamente a mesma operação.
A documentação pública também informa atualmente 99,99% de uptime da API e latência mediana inferior a 200 milissegundos.
Na prática, isso permite construir uma arquitetura na qual:
API cria e consulta;
webhook comunica mudanças;
IDs relacionam os eventos;
consultas recuperam o estado quando necessário.
Como webhooks ajudam na conciliação?
Considere uma empresa que emitiu 50 mil cobranças.
O ERP já possui um identificador para cada uma.
Quando uma cobrança é paga, o webhook informa a mudança.
O sistema utiliza o identificador para localizar o registro correspondente.
A baixa pode acontecer automaticamente.
O financeiro precisa analisar principalmente os casos que não seguiram esse fluxo.
É a passagem de:
conferência de todas as transações
para:
gestão das exceções.
Quando polling ainda faz sentido?
Polling continua sendo útil em diferentes situações.
Por exemplo:
Sistemas legados: a arquitetura não consegue receber webhooks.
Baixo volume: a quantidade de consultas é pequena e previsível.
Verificação periódica: a empresa precisa validar estados independentemente dos eventos recebidos.
Recuperação: uma operação permaneceu tempo demais sem atualização.
Reconciliação: o sistema executa uma varredura para confirmar que sua base continua consistente com a fonte financeira.
O problema não é utilizar polling.
É utilizá-lo como única estratégia em uma operação de alto volume quando existe uma arquitetura orientada a eventos disponível.
Como escolher a frequência de polling?
Quanto menor o intervalo, mais rapidamente a aplicação descobre uma mudança.
Mas também aumenta o número de requisições.
Por exemplo, para 10 mil operações pendentes:
a cada 1 minuto → até 600 mil consultas por hora
a cada 5 minutos → até 120 mil consultas por hora
a cada 15 minutos → até 40 mil consultas por hora
São exemplos teóricos que assumem todas as operações sendo consultadas durante toda a hora.
Eles mostram o trade-off:
menor intervalo = informação potencialmente mais rápida + mais requisições.
Com webhook, esse problema muda porque a comunicação é disparada pelo evento.
Qual arquitetura usar para pagamentos em alto volume?
Um desenho possível é:
API para criação
↓
fila para processamento
↓
instituição financeira
↓
webhook para atualização
↓
fila de eventos
↓
ERP
↓
rotina periódica de reconciliação
Esse modelo não depende de um único mecanismo.
Se o webhook chegar, o processamento acontece rapidamente.
Se algum evento falhar, a rotina de reconciliação pode identificar a diferença.
Essa redundância é importante em operações financeiras.
O que avaliar nos webhooks de um banco ou fintech?
Antes da integração, pergunte:
- Quais eventos possuem webhook?
- Existe assinatura para validar a origem?
- Cada evento possui ID único?
- Existem retries?
- Qual é a política de retry?
- Eventos podem ser recuperados depois?
- Como lidar com duplicidades?
- Eventos podem chegar fora de ordem?
- Existe Sandbox?
- O comportamento do Sandbox é semelhante ao de produção?
- Posso consultar o recurso pela API?
- Existe histórico para reconciliação?
- Como são monitoradas falhas de entrega?
Essas perguntas são mais importantes do que simplesmente confirmar se “tem webhook”.
Afinal, webhook ou polling: qual usar em pagamentos?
Para pagamentos, webhooks geralmente devem ser o mecanismo principal para receber mudanças de status, enquanto consultas à API podem funcionar como mecanismo complementar para confirmação, recuperação e reconciliação.
Webhook reduz a necessidade de perguntar continuamente se algo mudou.
Polling permite verificar o estado quando necessário.
Em operações financeiras críticas, combinar os dois cria uma arquitetura mais resiliente.
A questão, portanto, não é simplesmente escolher entre:
webhook ou polling.
É definir qual mecanismo informa a mudança e qual garante que, mesmo diante de uma falha de comunicação, nenhuma movimentação financeira deixe de ser identificada pelo sistema da empresa.
