Escolher Webhooks, WebSocket ou polling de RPC

Use Webhooks de endereços para entrega em um receptor HTTPS, WebSocket para assinaturas em tempo real suportadas e polling com limites quando o fluxo exigir seu próprio cursor e recuperação.

Criar ouvintes de eventos on-chain para desenvolvedores e agentes de IA exige alinhar a arquitetura da aplicação com as capacidades da rede, garantias de entrega, restrições do receptor e custo operacional.

Matriz de decisão

A tabela abaixo compara todos os três mecanismos de integração entre capacidades de rede suportadas, requisitos de infraestrutura, estratégias de recuperação e modelos de cobrança:

Quando escolher Webhooks de endereços

Escolha a API de Webhooks de Blockchain quando seu backend operar como um serviço web padrão capaz de receber requisições HTTPS de entrada:

• Grandes listas de endereços: Monitore depósitos ou saques em milhares de endereços de clientes sem manter sockets persistentes por carteira.
• Receptores serverless ou em contêineres: Funções serverless (AWS Lambda, Cloudflare Workers) são iniciadas com a chegada de webhooks e não precisam manter conexões ativas contínuas.
• Tentativas automáticas e replay: Interrupções transitórias no receptor são mitigadas pelo recuo automático de tentativas. Dentro da janela de retenção do servidor, entregas perdidas podem ser reenviadas usando o endpoint de replay.
• Considerações sobre o limite de ativação: A correspondência começa apenas depois que a alteração da assinatura for aplicada (applied_from_block). Eventos ocorridos antes da adição de um endereço ou enquanto a assinatura estava offline devem ser consultados pelo histórico de logs de RPC.

Revise os fluxos de verificação de assinatura e replay antes de expor receptores de webhook em produção.

Quando escolher assinaturas via WebSocket

Escolha as Assinaturas via WebSocket quando baixa latência for necessária e seu processo puder manter um socket de saída de longa duração:

• Cabeçalhos de blocos em tempo real: Receba newHeads via streaming assim que cada bloco for anexado ao topo da cadeia.
• Filtros de eventos de contrato: Receba via streaming logs de contratos em tempo real que correspondam a um endereço ou a um topic0 específico.
• Ambientes privados: Ideal para scripts locais, agentes de CLI ou serviços de backend atrás de NAT ou firewalls que não podem expor uma porta HTTPS pública de entrada.
• Verificação de disponibilidade de rede: WebSocket é suportado na Robinhood Chain (slug de rede robinhood_mainnet, Chain ID 4663 e robinhood_testnet). A HyperEVM atualmente não tem suporte a WebSocket (ws: false); tentar uma conexão WebSocket com uma rede não atendida retorna HTTP 404 (unknown_chain).
• Disciplina de desconexão: Notificações via WebSocket não são retidas no servidor durante desconexões. Quando o socket cai, os clientes devem se reconectar com recuo exponencial aleatório e preencher retroativamente os blocos perdidos via eth_getLogs.

Consulte o guia de Assinaturas via WebSocket para obter limites de filtros, limites de conexão (20 por chave, 50 por conta) e exemplos de conexão com viem.

Quando escolher polling de RPC com limites

Escolha o polling de JSON-RPC com limites ao executar workers agendados, pipelines de dados ou operar em redes onde o WebSocket não está disponível:

• Redes sem WebSocket: A HyperEVM (hyperevm_mainnet) oferece atualmente acesso HTTP a JSON-RPC, mas não a WebSocket (ws: false). Fazer polling de eth_blockNumber e consultar eth_getLogs dentro dos intervalos de blocos suportados viabiliza o processamento de eventos na HyperEVM.
• Ritmo de consulta controlado: O polling permite que desenvolvedores e agentes de IA regulem a frequência de requisições, gerenciem o consumo de Compute Units em relação aos limites de taxa (400 CU/s por chave por padrão em contas gratuitas) e evitem quedas de socket durante tarefas de longa duração.
• Limites de intervalo de blocos: Consultas autenticadas de eth_getLogs são limitadas pelo max_logs_block_range da rede (1.000 blocos). Exceder esse limite retorna o código de erro -32602 (logs_range_too_large). Divida intervalos mais amplos em partes consecutivas que não excedam 1.000 blocos.

Veja o guia de backfill de logs na HyperEVM e o guia de intervalo de blocos do eth_getLogs para algoritmos de divisão em partes.

Para uma lista completa de verificação de cargas de trabalho e testes rápidos, comece com Como escolher um provedor de RPC.

Ao escolher um provedor para polling de baixo volume, compare provedores quanto à cobrança padrão de RPC e cobertura. Compare a cobrança por uso com os custos de períodos de teste e assinaturas; os custos de notificação e backfill utilizam métricas diferentes das leituras de RPC.

Guias de implementação

WebSocket na Robinhood Chain

Para newHeads em tempo real ou logs filtrados na Robinhood Chain, siga o guia de Assinaturas via WebSocket para autenticação e requisições de assinatura. Após uma desconexão, reconecte com recuo, assine novamente e preencha blocos perdidos a partir de um cursor salvo com eth_getLogs; deduplique os logs por (blockHash, transactionHash, logIndex).

Polling com limites na HyperEVM

Para a HyperEVM (hyperevm_mainnet), siga o guia de backfill de logs na HyperEVM para polling com limites e recuperação. Faça consultas a partir do cursor salvo em partes dentro de max_logs_block_range, persista eventos e progresso juntos após o processamento bem-sucedido e repita intervalos incompletos. Verifique a continuidade da cadeia e examine intervalos sobrepostos para tratar reorgs.

Próximos passos

• Explore o diretório de conjuntos de dados para ver todos os conjuntos de dados indexados pela BlockVectra.
• Consulte o plano gratuito e os preços para verificar o que sua conta inclui.
• Entre no console para criar uma API key.