Webhooks Polygon : Recevez des événements on-chain en temps réel sans polling

Les webhooks Polygon sont des rappels HTTP qu’un service envoie à votre serveur lorsqu’un événement se produit sur la chaîne Polygon, comme un dépôt USDC arrivant sur l’une de vos adresses. Vous enregistrez une URL, le fournisseur surveille la chaîne, et votre backend reçoit un POST signé au lieu d’interroger un nœud RPC toutes les quelques secondes. Ce guide explique comment cela fonctionne sur Polygon PoS, ce qui peut mal tourner, et comment construire un gestionnaire auquel vous pouvez confier de l’argent.

TL;DR

• Un webhook remplace l’interrogation (polling) : le fournisseur surveille Polygon et pousse les événements (dépôts, transferts, mouvements de jetons) vers votre point de terminaison.
• Les blocs Polygon arrivent environ toutes les 2 secondes, donc les événements sont rapides, mais vous avez toujours besoin d’une politique de confirmation avant de créditer les fonds.
• Traitez chaque livraison comme potentiellement dupliquée, en retard ou hors ordre : vérifiez la signature, stockez l’identifiant d’événement, et traitez de manière idempotente.
• Acquittez rapidement, effectuez le travail dans une file d’attente, et réconciliez avec la chaîne selon un calendrier.
• Les Webhooks Chaingateway fournissent des événements Polygon pré-décodés et signés HMAC, vous évitant ainsi d’exécuter des nœuds et d’analyser les logs.

Table des matières

• Ce qu’est réellement un webhook Polygon
• Pourquoi les webhooks battent le polling sur Polygon
• Confirmations, finalité et réorganisations sur Polygon PoS
• À quoi ressemble un gestionnaire de webhook Polygon sûr
• Jetons et cas limites sur Polygon
• Le construire soi-même ou utiliser une API unifiée
• Notre point de vue : les webhooks sont un problème de registre, pas de notification
• Obtenir des webhooks Polygon avec Chaingateway
• Une liste de contrôle pour le lancement
• FAQ
• Sources

Ce qu’est réellement un webhook Polygon

Polygon PoS est une chaîne EVM. Chaque transfert ERC-20, qu’il s’agisse d’USDC, d’USDT ou d’un jeton que vous avez émis vous-même, émet un log Transfer. Le POL natif se déplace comme un simple transfert de valeur sans aucun log. Le RPC brut vous donne les deux sous des formes différentes : des logs pour les jetons, des données de transaction et de trace pour les pièces natives. Si vous voulez savoir qu’un client a payé, vous devez assembler cette image vous-même.

Un service de webhook fait l’assemblage. Vous vous abonnez à une adresse (ou un ensemble d’adresses), et lorsqu’un événement correspondant se produit, le service envoie une charge utile JSON à votre URL. Une bonne charge utile vous indique la chaîne, le hachage de transaction, l’expéditeur, le destinataire, le jeton, le montant en unités humaines, le numéro de bloc et un identifiant d’événement unique. C’est la différence entre « voici un log avec des sujets en hexadécimal » et « le client 4812 a payé 250 USDC ».

Trois choses que les gens recherchent sous ce mot-clé sont en réalité trois outils différents :

• Webhooks d’adresse et de paiement : notifiez-moi lorsque des fonds arrivent sur ces adresses. C’est ce dont les flux de paiement ont besoin.
• Webhooks d’événements de contrat : notifiez-moi lorsqu’un contrat intelligent donné émet un événement donné. C’est ce dont les backends dApp et les analyses ont besoin.
• Webhooks de niveau protocole : notifications d’un produit Polygon lui-même sur ses propres opérations. Ceux-ci appartiennent à la documentation de ce produit, pas à un écouteur de chaîne général.

Cet article traite du premier type, avec des notes sur le second.

Pourquoi les webhooks surpassent le polling sur Polygon

Polygon produit un bloc environ toutes les deux secondes, selon cette référence sur les temps de confirmation. Si vous interrogez un point de terminaison RPC pour les nouveaux blocs et filtrez les logs vous-même, vous êtes confronté à un compromis sans bonne réponse :

• Interroger toutes les quelques secondes et vous épuisez les limites de taux et payez pour des réponses majoritairement vides.
• Interroger chaque minute et votre client fixe un indicateur de chargement pendant une minute après avoir payé.
• Manquer une plage après un redémarrage et vous avez un trou silencieux dans votre registre.

Les webhooks inversent la situation. Le fournisseur assure la surveillance, les nouvelles tentatives et la comptabilité des blocs. Votre travail se réduit à l’exécution d’un point de terminaison qui gère correctement les événements. Nous approfondissons les compromis d’architecture dans notre article sur les webhooks vs WebSockets, y compris le motif d’ingestion, de file d’attente et de diffusion que nous recommandons.

Confirmations, finalité et réorganisations sur Polygon PoS

Un webhook qui se déclenche dès la première détection d’une transaction est rapide. Il n’est pas final. Avant de livrer des biens ou de créditer un solde, décidez combien de blocs vous attendez.

Polygon PoS confirme rapidement. Un suivi indique une première confirmation typique entre 1 et 5 secondes, et note que les plateformes d’échange attendent généralement 128 blocs, soit environ 4 à 5 minutes, pour se prémunir contre les réorganisations. Une autre source rapporte que la mise à niveau Heimdall v2 en juillet 2025 a réduit la finalité dure à environ 5 secondes. Les pratiques diffèrent entre les plateformes d’échange et les outils, et les mises à niveau du réseau modifient les chiffres, donc consultez la documentation Polygon actuelle avant de fixer un seuil en production.

Une méthode pratique pour choisir consiste à lier la politique à la valeur en jeu :

Ce tableau est notre politique suggérée, pas une règle Polygon. Choisissez des chiffres qui correspondent à votre propre tolérance au risque et notez-les.

Dans votre modèle de données, donnez à chaque paiement entrant un statut tel que detected, confirming et final. Montrez au client le premier état immédiatement et déplacez les fonds uniquement sur le dernier. Si votre fournisseur envoie des événements séparés au fur et à mesure que les confirmations s’accumulent, utilisez-les. Sinon, stockez le numéro de bloc du premier événement et comparez-le avec la tête de chaîne sur un minuteur.

À quoi ressemble un gestionnaire de webhook Polygon sûr

La documentation développeur de Polygon inclut un guide sur la réception de webhooks pour l’un de leurs propres produits, et les principes qu’il enseigne s’appliquent à chaque intégration de webhook : vérifiez la livraison et appliquez-la sans double traitement ni application d’un état obsolète. Voici la même discipline pour les événements de chaîne.

1. Vérifiez la signature avant toute autre chose

Quiconque trouve votre URL peut y faire un POST. Sans vérification, un attaquant peut envoyer un faux « 250 USDC reçus » et repartir avec votre produit. Rejetez les requêtes non signées ou mal signées avec un 401 et n’analysez pas le corps plus loin.

Chaingateway signe les requêtes avec HMAC. Vous calculez la signature sur le corps brut de la requête avec votre secret partagé et la comparez à l’aide d’une comparaison en temps constant. Utilisez les octets bruts, pas un objet JSON re-sérialisé, car la re-sérialisation modifie les espaces blancs et l’ordre des clés et casse la correspondance. Notre article sur une nouvelle fonctionnalité pour renforcer la sécurité des webhooks explique les options de vérification en détail.

Pour une vision d’ensemble de la protection des clés, des points de terminaison et des processus opérationnels autour des actifs numériques, cet aperçu de la sécurité et de la gestion des risques des actifs numériques est une lecture utile pour l’aspect non technique du problème.

2. Rendre le traitement idempotent

Partez du principe d’une livraison au-moins-une-fois. Un délai d’attente de votre côté incite l’expéditeur à réessayer, et une nouvelle tentative peut arriver après que vous ayez déjà traité la première copie. Stockez une clé unique par événement, idéalement le hachage de transaction plus l’index de log, ou l’ID d’événement que le fournisseur fournit. Mettez une contrainte d’unicité dessus dans votre base de données :

INSERT INTO processed_events (event_key, received_at)
VALUES ($1, now())
ON CONFLICT (event_key) DO NOTHING;

Si l’insertion affecte zéro ligne, vous avez déjà vu cet événement. Renvoyez 200 et arrêtez-vous. Faites l’insertion et la mise à jour du solde dans la même transaction de base de données pour qu’un crash ne puisse pas laisser l’un sans l’autre.

3. Acquitter vite, travailler plus tard

Renvoyez un 2xx dès que l’événement est vérifié et stocké en toute sécurité. Faites le travail lent, comme l’envoi d’e-mails au client, la mise à jour des registres et l’appel d’autres services, depuis une file d’attente. Si votre gestionnaire prend trente secondes, l’expéditeur expirera et réessaiera, et vous déboguerez des doublons.

4. Ne pas faire confiance à l’ordre

Deux événements concernant le même paiement peuvent arriver dans n’importe quel ordre, par exemple une mise à jour de confirmation avant la détection d’origine. Comparez les numéros de bloc ou les champs de séquence et ignorez tout ce qui est plus ancien que l’état que vous détenez déjà. Ne laissez jamais un événement “détecté” tardif écraser un enregistrement “final”.

5. Valider ce que la charge utile affirme

Vérifiez que le destinataire est une adresse que vous avez émise, que le contrat de jeton est un que vous acceptez, et que le montant correspond à la facture. Cela importe sur Polygon plus que prévu, car n’importe qui peut déployer un jeton nommé “USDC” et l’envoyer à votre adresse. Comparez les adresses de contrat, jamais les symboles.

6. Prévoir l’échec

Votre serveur sera en panne à un moment donné. Décidez à l’avance comment vous récupérez :

• Utilisez un fournisseur qui réessaie les livraisons échouées.
• Exécutez un travail de réconciliation, par exemple toutes les quelques minutes, qui vérifie les soldes ou les transferts récents pour vos adresses et signale tout ce que votre journal de webhook n’a jamais vu.
• Alertez lorsqu’aucun événement n’arrive pendant une durée anormalement longue. Sur un système chargé, le silence est un signal.

Les webhooks sont votre voie rapide. La réconciliation est votre filet de sécurité. Exécutez les deux.

Jetons et cas limites sur Polygon

USDC et USDT. Les paiements en stablecoins sont la principale raison pour laquelle les développeurs configurent des webhooks Polygon, car les frais sont bas et le règlement est rapide. Assurez-vous de savoir quel contrat chaque stablecoin utilise sur Polygon et mettez ces adresses en liste blanche, comme décrit ci-dessus.

POL natif. Les transferts natifs n’émettent pas de logs de jeton, donc un écouteur construit uniquement sur les événements Transfer les manquera. Confirmez que votre fournisseur signale aussi les mouvements de la pièce native si vous prévoyez d’accepter du POL.

Paiements contract-to-address. Un paiement peut provenir d’un portefeuille de contrat intelligent ou d’un multisig, et non d’un compte simple. Ne supposez pas que l’expéditeur est le client. Liez les paiements aux clients par l’adresse de réception que vous avez générée pour eux, et non par l’expéditeur.

Transactions échouées et annulées. Une transaction annulée consomme du gaz mais ne déplace rien. N’agissez que sur les événements qui représentent des transferts réussis.

Dust et tokens spam. Des tokens non sollicités apparaissent régulièrement dans les adresses. Ignorez les contrats que vous n’avez pas mis en liste blanche.

Construire soi-même ou utiliser une API unifiée

Il existe trois approches réalistes pour les notifications d’événements Polygon :

1. Exécuter votre propre nœud et listener. Contrôle maximal, mais vous gérez les mises à jour du nœud, la croissance du stockage, le décodage des logs, la gestion des réorganisations et la disponibilité. Pertinent lorsque l’infrastructure de chaîne est votre produit.
2. Utiliser un nœud ou un fournisseur de données à usage général et écrire le filtrage vous-même. Moins de charge opérationnelle, mais vous devez toujours construire les abonnements, les retentatives, le décodage et la couche de signature.
3. Utiliser une API axée sur les paiements qui fournit des événements décodés et signés. Vous écrivez le point de terminaison et la logique métier, rien d’autre.

Pour une équipe qui souhaite accepter ou envoyer des cryptomonnaies dans son produit, la troisième approche atteint généralement la production le plus rapidement. Nous comparons les options plus en détail dans APIs Blockchain comparées : 6 types et quand utiliser chacun.

Notre perspective : les webhooks sont un problème de grand livre, pas un problème de notification

La plupart des bugs d’intégration que nous voyons ne concernent pas la réception de la requête HTTP. Ils concernent ce qui se passe après. Les équipes traitent un webhook comme un déclencheur (« paiement arrivé, expédiez-le ») alors qu’il s’agit en réalité d’une entrée pour un grand livre qui doit rester correct malgré les retentatives, les réorganisations et les redémarrages.

Cela façonne la façon dont nous construisons Chaingateway. Nous fournissons des événements pré-décodés, donc votre code lit un montant et un token, et non des topics de log encodés en hexadécimal. Nous signons chaque requête avec HMAC pour que votre point de terminaison puisse rejeter les falsifications. Et nous couvrons Polygon aux côtés d’Ethereum, Tron, Bitcoin, Solana, BNB Chain et Arbitrum via une seule API REST, donc votre logique de gestion reste la même lorsque vous ajoutez une deuxième chaîne.

Notre conseil : écrivez votre code d’idempotence et de réconciliation en premier, avant le chemin nominal. Si vous pouvez rejouer le même événement dix fois et mélanger trois événements pour finir avec le bon solde, le reste est facile. Notre article sur le traitement automatique des dépôts avec les webhooks détaille ce flux de bout en bout.

— Bitblade

Obtenir des webhooks Polygon avec Chaingateway

Avec les Webhooks Chaingateway, vous créez des portefeuilles ou enregistrez des adresses via l’API, vous abonnez aux événements de paiement et recevez des notifications signées sur votre point de terminaison. La page API Polygon traite de l’envoi et de la réception d’USDC et d’USDT sur Polygon, et la page API Blockchain couvre les portefeuilles, les transferts, les données de transaction décodées et l’estimation du gaz sur les chaînes prises en charge.

Les forfaits sont publiés sur la page de tarification :

L’accès payant commence après un essai gratuit, vous pouvez donc tester le flux complet, y compris les vérifications de signature et la gestion des doublons, avant de vous engager.

Une liste de contrôle pour le lancement

Avant de diriger le trafic de production vers votre point de terminaison, passez en revue ceci :

• HTTPS uniquement, avec un certificat valide.
• Signature vérifiée sur le corps brut, comparaison en temps constant.
• Contrainte d’unicité sur la clé d’événement.
• 2xx retourné en quelques secondes, travail déplacé vers une file d’attente.
• Adresses de contrats sur liste blanche, montants et destinataires validés.
• Modèle d’état avec états en attente et finaux, et un seuil de confirmation documenté.
• Tâche de réconciliation et alerte pour les événements manquants.
• Secrets stockés en dehors du dépôt et rotatifs sans temps d’arrêt.
• Un test de rejeu : envoyez le même événement plusieurs fois, et dans le désordre, en staging.

Sources

• Référence Polygon Confirmation Time
• Temps de confirmation USDT par réseau
• Documentation Développeur Polygon

Recommandé

• Webhooks Blockchain & Notifications d’événements
• Webhooks vs WebSockets pour les Développeurs : Ingest, Queue, Fan Out Pattern
• L’utilisation des Webhooks pour traiter les dépôts automatiquement