Existem duas formas de acompanhar eventos na plataforma: polling (consultando a API periodicamente) e webhooks (recebendo notificações quando os eventos ocorrem). Cada abordagem tem seus casos de uso.
Comparação
| Polling | Webhooks |
|---|
| Como funciona | Você consulta a API em intervalos regulares | A plataforma envia uma requisição ao seu servidor |
| Latência | Alta — depende do intervalo de consulta | Baixa — notificação imediata |
| Carga na API | Alta — requisições constantes mesmo sem eventos | Baixa — requisição apenas quando há evento |
| Complexidade | Menor — sem endpoint exposto | Maior — requer endpoint HTTPS público |
| Confiabilidade | Você controla a frequência | Depende de rede e disponibilidade do seu servidor |
Quando usar webhooks
Webhooks são a abordagem recomendada para a maioria dos casos:
- Atualizar o status de um pedido assim que o PIX é recebido
- Disparar notificações ou e-mails ao cliente
- Acionar lógica de negócio em tempo real
Quando usar polling
Polling pode ser útil em cenários específicos:
- Reconciliação: verificar periodicamente se todos os eventos foram processados corretamente
- Recuperação de falhas: identificar eventos perdidos por indisponibilidade do seu servidor
- Ambientes sem endpoint público: servidores internos sem exposição à internet
Recomendação
Use webhooks como mecanismo principal e polling como fallback de reconciliação. Por exemplo, um job noturno que consulta a API e compara com os eventos já processados garante que nenhum evento seja perdido.
Ao usar polling para reconciliação, filtre por updated_at para buscar apenas os registros alterados desde a última consulta e reduzir o volume de dados retornados.
