Webhook / Polling

Definição

Webhook e polling são os dois modelos clássicos para informar um cliente de uma mudança de estado do lado do servidor (pagamento liquidado, transferência recebida, documento assinado).

• Webhook (push): o servidor envia uma requisição HTTP ao cliente assim que um evento ocorre.
• Polling (pull): o cliente consulta periodicamente o servidor para ver se há novidades.

A escolha é estruturante para qualquer integração de API fintech, com implicações importantes na latência, na confiabilidade, na complexidade e no custo.

Modelo webhook

Baixa latência, carga mínima (uma mensagem por evento), mas complexidade do lado do cliente (endpoint público, assinatura, retry, idempotência) e um endpoint a manter disponível 24/7.

Modelo polling

Latência média (N segundos), carga elevada (N requisições por minuto e por recurso), mas baixa complexidade do cliente (um simples GET) e nenhum endpoint a expor.

Comparação detalhada

Casos de uso fintech

• Webhook (preferido): Stripe, Adyen, Mollie (notificações de pagamento), Bridge, Tink, TrueLayer (PIS), DocuSign, Yousign (assinatura), Sumsub, Onfido (KYC).
• Polling: apps mobile sem backend, ou evento urgente e frequente (status de blockchain) — raro em produção.

Boas práticas de webhook

• Segurança: sempre verificar a assinatura (HMAC ou RFC 9421), HTTPS, IP allowlisting, verificação do timestamp (anti-replay).
• Confiabilidade: retry exponencial do lado do servidor, idempotency key do lado do cliente (processar cada evento uma única vez), ACK 2xx rápido (caso contrário, enfileiramento assíncrono), ordem não garantida.
• Observabilidade: registrar todos os webhooks, monitorar a taxa de erro e a latência do ACK, alertar sobre os retries (ferramentas: Hookdeck, Svix).

Boas práticas de polling

Backoff exponencial (não martelar a cada segundo), ETag / If-None-Match (304 se nada mudar), long polling (o servidor mantém a conexão por até 30 s) e paginação por cursor a partir do último checkpoint.

Webhook + polling = o melhor dos dois

Muitas fintechs oferecem os dois: o webhook como canal principal, o polling como fallback e uma reconciliação periódica (GET) para garantir que nenhum evento foi perdido. Stripe, Bridge e Adyen recomendam esse padrão híbrido.

Alternativas modernas

Server-Sent Events (push unidirecional), WebSockets (full-duplex, tempo real intensivo), gRPC streaming e MQTT/AMQP/Kafka para volume muito alto. Os webhooks continuam dominantes em fintech por serem simples, compatíveis com REST e universalmente suportados.

O que webhook / polling não é

• Não é um protocolo: são padrões sobre HTTP, não standards formais.
• Webhook não é um callback: o callback é inline em uma requisição, o webhook é uma chamada autônoma.
• Polling não é retry: o polling é regular, o retry ocorre em caso de falha.
• Não é garantia de exactly-once por si só: é preciso webhook + idempotência + checkpoint na base.

No ecossistema PSD2 / Open Finance

• PIS: o Berlin Group oferece uma notification_url (webhook) para sinalizar o fim de um pagamento.
• AIS: poucos webhooks (os ASPSPs raramente fazem push), daí um modelo mais de polling para atualizar.
• PSD3 / FIDA: devem padronizar os webhooks (consentimento, compartilhamento de dados).
• VoP: síncrono (request/response).
• Wero / SCT Inst: push notification mobile, próximo do modelo webhook do lado do app.

Exemplos concretos

• Stripe: webhooks para ~200 tipos de eventos (payment_intent.succeeded, charge.refunded), com dashboard de configuração e simulação.
• Bridge: webhooks payment.completed, account.refreshed, consent.expiring, assinados em HMAC SHA-256.
• Sumsub: webhook applicantReviewed ao fim do KYC.
• Ferramentas: ngrok e RequestBin para testar localmente, Svix e Hookdeck em produção.
• Custo: um player ingênuo que faz polling de 100 mil clientes a cada 30 s gera 3,3 mi de requisições/hora — a migração para o webhook reduz o custo em ~99%.
• Exactly-once falho: creditar um cliente a cada webhook sem idempotência resulta, após um retry, em um crédito em dobro — sempre deduplicar por event_id.