Choisir entre Webhooks, WebSocket ou polling RPC
Comparez les notifications d'adresses, les abonnements socket et le polling borné selon la prise en charge des chaînes, la récupération, les prérequis du récepteur et la facturation.
Utilisez les Webhooks d'adresse pour la livraison vers un récepteur HTTPS, WebSocket pour les abonnements en direct pris en charge et le polling borné lorsque le flux de travail nécessite son propre curseur et sa propre récupération.
La mise en place d'écouteurs d'événements on-chain pour les développeurs et les agents IA implique d'adapter l'architecture applicative aux capacités des réseaux, aux garanties de livraison, aux contraintes du récepteur et aux coûts opérationnels.
Matrice de décision
Le tableau ci-dessous compare les trois mécanismes d'intégration selon les fonctionnalités réseau prises en charge, les exigences d'infrastructure, les stratégies de récupération et les modèles de facturation :
| Dimension | Webhooks d'adresse | Abonnements WebSocket | Polling RPC borné |
|---|---|---|---|
| Mécanisme principal | Notification push livrée par HTTPS POST à un point de terminaison public | Abonnement en flux pull sur une connexion TLS persistante (wss://) | Requêtes JSON-RPC HTTP par lots initiées par le client ou planifiées |
| Disponibilité des chaînes | Tous les réseaux pris en charge déclarés dans GET /v1/push/chains | Pris en charge sur Robinhood Chain (robinhood_mainnet et robinhood_testnet) ; les réseaux non desservis ont ws: false et renvoient HTTP 404 | Tous les réseaux pris en charge dans GET /v1/chains via le RPC public sans clé ou JSON-RPC authentifié |
| Exigences pour le récepteur | URL HTTPS accessible publiquement, certificat TLS valide, réponse 2xx dans le délai imparti, vérification de signature HMAC SHA-256 sur le corps brut | Connexion cliente sortante TCP/TLS (wss://) ; gestion des battements de cœur ping/pong et du délai exponentiel de reconnexion | Client HTTP sans état ou worker planifié ; stocke un curseur de bloc local |
| Livraison et ordonnancement | Livraison au moins une fois avec repli exponentiel des tentatives ; le récepteur doit dédupliquer par id d'événement, ou par ref + type d'un abonnement à l'autre | Trames strictement ordonnées sur un socket actif unique ; notifications ignorées en cas de déconnexion | Réponses déterministes en mode pull pour des hauteurs de blocs confirmées ; le client cadence l'exécution |
| Réorganisations de chaîne | Notifications de contrôle émises pour chain.reorg ; le récepteur ignore les événements remplacés avant d'appliquer les rejeux canoniques | Les notifications de logs comportent "removed": true pour les logs réorganisés ; newHeads nécessite la vérification du hash parent | Le client suit la continuité de la chaîne via parentHash à chaque cycle de polling pour détecter les réorganisations |
| Récupération sur défaillance | La fenêtre de rétention du serveur permet le rejeu via POST /v1/push/subscriptions/{id}/replay ; les écarts avant le bloc d'activation nécessitent un rattrapage par eth_getLogs | Aucune file d'attente côté serveur ; le client se reconnecte et rattrape les plages manquées via eth_getLogs dédupliqué par (blockHash, transactionHash, logIndex) | Reprend les requêtes à partir du last_synced_block stocké ; partitionne les segments selon le max_logs_block_range du réseau issu de GET /v1/chains |
| Modèle de facturation | Frais quotidiens d'adresse par groupe, basés sur le nombre maximal d'adresses en ligne durant la journée UTC, plus CU pour les événements de données livrés ; voir Facturation des Webhooks | Handshake et battements de cœur non facturés ; eth_subscribe / eth_unsubscribe et unités de notification de socket vidées facturés en CU | Facturé par requête en Compute Units : eth_blockNumber, eth_call, eth_getLogs ; poids des méthodes et CU par dollar issus de GET /v1/plans, affichés ci-dessous |
| Idéal pour | Surveillance des dépôts utilisateurs, suivi des adresses de hot-wallets, paiements marchands, webhooks d'événements asynchrones | newHeads en temps réel et logs filtrés, bots réactifs, interfaces interactives sur les réseaux pris en charge | Rapprochement par lots, tâches cron, pipelines ETL, chaînes sans prise en charge de WebSocket (telles qu'HyperEVM) |
Paramètres de conversion actifs
1 USD = 10,000 unités de facturation, 1 unité de facturation = 1,000 CU (1 USD = 10,000,000 CU).
Formule : Poids en CU × 1 000 000 ÷ (10,000 × 1,000) USD.
| Méthode | CU par appel | Prix par million d'appels (USD) |
|---|---|---|
eth_blockNumber | 1 | $0.10 |
eth_call | 15 | $1.50 |
eth_getLogs | 30 | $3.00 |
debug_traceTransaction | 100 | $10.00 |
data.block | 5 | $0.50 |
Quand choisir les Webhooks d'adresse
Choisissez l'API Webhook blockchain lorsque votre backend fonctionne comme un service web standard capable de recevoir des requêtes HTTPS entrantes :
- Listes volumineuses d'adresses : surveillez les dépôts ou retraits sur des milliers d'adresses de clients sans maintenir de sockets persistants par wallet.
- Récepteurs serverless ou conteneurisés : les fonctions serverless (AWS Lambda, Cloudflare Workers) se déclenchent à l'arrivée des webhooks et n'ont pas besoin de maintenir des connexions continues actives.
- Nouvelles tentatives et rejeu automatisés : les pannes temporaires de récepteurs sont atténuées par un repli automatique des tentatives. Dans la limite de la fenêtre de rétention du serveur, les livraisons manquées peuvent être relivrées via le point de terminaison de rejeu.
- Considérations relatives à la frontière d'activation : la mise en correspondance ne commence qu'après l'application de la modification de l'abonnement (
applied_from_block). Les événements survenus avant l'ajout d'une adresse ou pendant qu'un abonnement étaitofflinedoivent être interrogés via les logs RPC historiques.
Examinez les flux de vérification de signature et de rejeu avant d'exposer des récepteurs de webhooks en production.
Quand choisir les abonnements WebSocket
Choisissez les abonnements WebSocket lorsqu'une faible latence est requise et que votre processus peut maintenir un socket sortant de longue durée :
- En-têtes de blocs en direct : diffusez
newHeadsà mesure que chaque bloc est ajouté au sommet de la chaîne. - Filtres d'événements de contrats : diffusez en temps réel les
logsde contrats correspondant à une adresse ou à untopic0spécifique. - Environnements privés : idéal pour les scripts locaux, les agents CLI ou les services backend derrière un NAT ou un pare-feu qui ne peuvent pas exposer de port public HTTPS entrant.
- Vérification de la disponibilité du réseau : WebSocket est pris en charge sur Robinhood Chain (slug réseau
robinhood_mainnet, Chain ID 4663 etrobinhood_testnet). HyperEVM ne prend actuellement pas en charge WebSocket (ws: false) ; toute tentative de connexion WebSocket à une chaîne non desservie renvoie HTTP 404 (unknown_chain). - Discipline en cas de déconnexion : les notifications WebSocket ne sont pas conservées sur le serveur lors des déconnexions. En cas de coupure du socket, les clients doivent se reconnecter avec un repli exponentiel aléatoire et rattraper les blocs manqués via
eth_getLogs.
Consultez le guide des abonnements WebSocket pour connaître les limites de filtrage, les plafonds de connexion (20 par clé, 50 par compte) et des exemples de connexion avec viem.
Quand choisir le polling RPC borné
Choisissez le polling JSON-RPC borné lors de l'exécution de workers planifiés, de pipelines de données ou sur les réseaux où WebSocket n'est pas disponible :
- Réseaux sans WebSocket : HyperEVM (
hyperevm_mainnet) fournit actuellement un accès HTTP JSON-RPC mais aucun support WebSocket (ws: false). Le polling deeth_blockNumberet l'interrogation deeth_getLogsdans les limites de plages de blocs prises en charge permettent le traitement des événements HyperEVM. - Cadence de requêtes contrôlée : le polling permet aux développeurs et aux agents IA de réguler la fréquence des requêtes, de gérer la consommation de Compute Units par rapport aux limites de débit par clé et d'éviter les coupures de socket lors de tâches longues. Limites par clé — les valeurs par défaut sont 400 CU/s et un burst de 1,600 CU.
- Limites de plages de blocs : les requêtes
eth_getLogsauthentifiées sont plafonnées par lemax_logs_block_rangedu réseau issu de GET /v1/chains. Dépasser cette limite renvoie le code d'erreur-32602(logs_range_too_large). Découpez les intervalles plus larges en segments consécutifs ne dépassant pas lemax_logs_block_rangedu réseau cible.
| Chaîne | Slug de chaîne | max_logs_block_range (blocs) |
|---|---|---|
| Arbitrum One | arb_mainnet | 1,000 |
| Base | base_mainnet | 1,000 |
| BNB Smart Chain | bsc_mainnet | 1,000 |
| Ethereum | eth_mainnet | 1,000 |
| Ethereum Sepolia | eth_sepolia | 1,000 |
| HyperEVM | hyperevm_mainnet | 1,000 |
| Polygon | polygon_mainnet | 1,000 |
| Robinhood Chain | robinhood_mainnet | 1,000 |
| Robinhood Chain Testnet | robinhood_testnet | 1,000 |
Consultez le guide de rétro-remplissage des logs HyperEVM et le guide de plage de blocs eth_getLogs pour les algorithmes de découpage en segments.
Pour une liste de contrôle complète des charges de travail et des auto-tests, commencez par Comment choisir un fournisseur RPC.
Lors du choix d'un fournisseur pour un polling à faible volume, comparez les fournisseurs pour la facturation et la couverture RPC standards. Comparez la facturation à l'usage avec les coûts d'essai et d'abonnement ; les coûts de notification et de rétro-remplissage utilisent des compteurs différents des lectures RPC.
Guides d'implémentation
WebSocket sur Robinhood Chain
Pour obtenir newHeads en temps réel ou des logs filtrés sur Robinhood Chain, suivez le guide des abonnements WebSocket pour l'authentification et les requêtes d'abonnement. Après une déconnexion, reconnectez-vous avec un délai d'attente, réabonnez-vous et rattrapez les blocs manqués à partir d'un curseur sauvegardé avec eth_getLogs ; dédupliquez les logs par (blockHash, transactionHash, logIndex).
Polling borné sur HyperEVM
Pour HyperEVM (hyperevm_mainnet), suivez le guide de rétro-remplissage des logs HyperEVM pour le polling borné et la récupération. Interrogez à partir du curseur sauvegardé par segments compris dans max_logs_block_range, persistez conjointement les événements et la progression après un traitement réussi, et réessayez les plages incomplètes. Vérifiez la continuité de la chaîne et balayez les plages chevauchantes pour gérer les réorganisations.
Prochaines étapes
- Parcourir le catalogue des jeux de données pour découvrir chaque jeu de données indexé par BlockVectra.
- Consulter le forfait gratuit et les tarifs pour vérifier ce que comprend votre compte.
- Se connecter à la console pour créer une API key.
Dernière mise à jour :
Push Webhook
Créez des abonnements d'adresses par HTTP, vérifiez les signatures du corps brut, dédupliquez les ID d'événements et récupérez les correspondances conservées ou les blocs manquants.
Abonnements WebSocket
Connectez-vous aux points de terminaison WebSocket de BlockVectra pour eth_subscribe newHeads et logs. Découvrez les modes de connexion, les règles de filtrage, le repli de reconnexion et la récupération.