Webhooks vs. polling: como construir integrações de Open Finance que escalam

Quem já integrou dados bancários conhece o dilema. Como saber que uma conexão terminou de sincronizar, que chegaram transações novas ou que o consentimento expirou? A resposta ingênua é consultar a API de tempos em tempos, o chamado polling. A resposta que escala é ouvir webhooks.

Polling: fácil de começar, caro de manter

No polling, sua aplicação pergunta periodicamente se há algo novo. Funciona, mas os problemas aparecem conforme a base cresce:

• Desperdício: a maioria das chamadas volta sem novidade.
• Latência: se você consulta de hora em hora, um dado novo pode esperar até uma hora para aparecer.
• Rate limits: milhares de conexões consultadas com frequência batem nos limites de requisição.
• Estado inconsistente: é fácil perder uma mudança de estado que aconteceu entre duas consultas.

Webhooks: a plataforma avisa você

Com webhooks, a plataforma de dados chama um endpoint seu quando algo acontece: uma conexão criada, atualizada ou com erro, ou dados novos disponíveis. Você reage ao evento e não faz consultas desnecessárias.

Na Malvo, os webhooks são a fonte da verdade sobre o estado de um Item, a conexão entre um usuário e uma instituição. Eventos como item/created e item/updated dizem quando agir.

Por que não confiar só no retorno do widget

No Open Finance, o usuário é redirecionado ao banco para autenticar e confirmar o compartilhamento, como descreve o FAQ do Open Finance Brasil. Ele pode fechar a aba antes de voltar. Por isso o callback de sucesso no navegador é best-effort: ajuda na experiência, mas não serve como registro. O webhook, que vai de servidor para servidor, serve.

Boas práticas para receber webhooks

1. Responda rápido e processe depois

Devolva sucesso assim que receber e validar o evento, e mande o processamento para uma fila. Endpoint lento gera timeout e reentrega.

2. Seja idempotente

Um evento pode chegar mais de uma vez. Use o identificador do evento para que processá-lo duas vezes não gere duplicidade.

3. Não dependa da ordem

Eventos podem chegar fora de ordem. Ao receber um, consulte o estado atual do recurso na API em vez de supor a sequência.

4. Valide a origem

Verifique a autenticidade de cada chamada como manda a documentação do provedor e exponha o endpoint apenas via HTTPS.

5. Monitore e tenha um plano B

Registre as falhas e mantenha uma reconciliação periódica, leve e pouco frequente, para cobrir algum evento perdido. É o único polling que vale manter.

Sincronização incremental

Quando chegar o aviso de dados novos, não baixe o histórico inteiro outra vez. Busque só o que mudou desde a última sincronização e atualize sua base usando chaves estáveis. O custo cai, os limites de requisição são respeitados e o banco continua consistente.

E fora do Brasil?

No Open Banking europeu e britânico, a conectividade AIS (Account Information Service) nem sempre notifica o agregador em tempo real. Nesse fluxo, o scheduler da Malvo consulta sessões e dados e emite os mesmos webhooks depois de persistir o resultado. Para a sua aplicação, o contrato não muda: você continua ouvindo eventos e não precisa implementar polling para cada país.

Arquitetura de referência

1. O backend se autentica na API e gera um token de conexão de curta duração.
2. O frontend abre o Connect Widget com esse token.
3. O usuário autoriza no banco.
4. O webhook item/created chega ao seu endpoint, e você registra o Item.
5. Os webhooks seguintes indicam dados disponíveis, e um worker busca contas e transações de forma incremental.
6. Uma reconciliação diária verifica os Items sem eventos recentes.

Erros comuns

• Tratar o callback do navegador como confirmação definitiva.
• Processar o webhook de forma síncrona e pesada.
• Não deduplicar eventos.
• Fazer polling agressivo "por garantia" e estourar rate limits.
• Expor credenciais de API no frontend.

Por que isso importa agora

O Open Finance Brasil chegou a 269,06 milhões de consentimentos ativos em 25/09/2026, segundo o dashboard oficial compilado pelo FintechNode. O estudo da Zetta citado pela Folha fala em cerca de 800 instituições participantes. Uma arquitetura de polling que aguenta cem conexões quebra com cem mil, e desenhar orientado a eventos desde o início evita refazer a integração depois.

Polling atrai pela simplicidade. Webhooks, com idempotência, processamento assíncrono e uma reconciliação leve como rede de segurança, são o que mantém a integração rápida, barata e consistente quando a base cresce.

A Malvo entrega webhooks como fonte da verdade no Open Finance Brasil e no Open Banking da Europa e do Reino Unido, com o mesmo contrato de API. Leia a documentação de webhooks da Malvo.