Passer au contenu principal
En bref
Les webhooks envoient des notifications en temps réel à votre serveur lorsque des événements se produisent : dépôts, retraits, swaps et plus encore. Au lieu d’interroger l’API, votre serveur reçoit des mises à jour instantanées dès que les transactions sont terminées.

Prérequis

Avant de configurer des webhooks, assurez-vous de disposer des éléments suivants :
1

Clé API

Obtenez votre clé API depuis le tableau de bord Blockradar. Rendez-vous dans Developers pour en générer une.
2

Endpoint webhook

Créez sur votre serveur un endpoint POST capable de recevoir des payloads JSON et de renvoyer une réponse 200 OK.
3

URL HTTPS (production)

En production, votre URL webhook doit utiliser HTTPS. Pour les tests en local, utilisez des outils comme ngrok ou webhook.site.
4

Portefeuille principal

Configurez votre URL webhook sur votre portefeuille principal depuis le tableau de bord.

Comment ça fonctionne

Lorsque vous envoyez une requête à un endpoint de l’API, vous vous attendez à obtenir une réponse quasi immédiate. Cependant, certaines requêtes peuvent prendre beaucoup de temps à traiter, ce qui peut entraîner des erreurs de timeout. Pour éviter une erreur de timeout, une réponse en attente est renvoyée. Comme vos enregistrements doivent être mis à jour avec l’état final de la requête, vous devez soit :
  1. Envoyer une requête pour obtenir une mise à jour (ce que l’on appelle couramment le polling), soit
  2. Écouter les événements à l’aide d’une URL webhook.
Conseil utile
Nous vous recommandons d’utiliser les webhooks plutôt que les callbacks ou le polling pour offrir de la valeur à vos clients. Avec les callbacks, nous n’avons aucun contrôle sur ce qui se passe du côté du client. Vous non plus. Les callbacks peuvent échouer si la connexion réseau de l’appareil du client est coupée ou faible, ou si l’appareil s’éteint après une transaction.

Polling ou webhooks

Le polling consiste à envoyer une requête GET à intervalles réguliers pour obtenir le statut final d’une requête. Par exemple, lorsque vous attribuez une adresse de dépôt à un client, vous continuez à demander les transactions liées à cette adresse jusqu’à en trouver une. Avec les webhooks, le serveur de ressources, ici Blockradar, envoie des mises à jour à votre serveur lorsque le statut de votre requête change. Ce changement de statut d’une requête est appelé un événement. Vous écoutez généralement ces événements sur un endpoint POST appelé votre URL webhook. Le tableau ci-dessous présente quelques différences entre le polling et les webhooks :

Créer une URL webhook

Une URL webhook est simplement un endpoint POST vers lequel un serveur de ressources envoie des mises à jour. L’URL doit analyser une requête JSON et renvoyer un 200 OK :
Lorsque votre URL webhook reçoit un événement, elle doit l’analyser et en accuser réception. Accuser réception d’un événement signifie renvoyer un 200 OK dans l’en-tête HTTP. Sans 200 OK dans l’en-tête de la réponse, nous continuerons à envoyer les événements pendant les 2 heures et 35 minutes suivantes :
  • Nous tenterons d’envoyer les webhooks 5 fois, avec un délai croissant entre chaque tentative, en commençant par 5 minutes et en augmentant de manière exponentielle jusqu’à 80 minutes. La durée totale de ces 5 tentatives sera d’environ 2 heures et 35 minutes.
Évitez les tâches de longue durée
Si votre fonction webhook comporte des tâches de longue durée, vous devez accuser réception de l’événement avant de les exécuter. Les tâches de longue durée entraînent un timeout de la requête et une réponse d’erreur automatique de votre serveur. Sans réponse 200 OK, nous réessayons comme décrit dans le paragraphe ci-dessus.

Tester les webhooks en local

Pendant le développement, vous pouvez configurer l’URL webhook de votre environnement de portefeuille principal TEST sur une adresse locale, telle que http://localhost ou 127.0.0.1. Pour exposer votre serveur local à Internet à des fins de test, vous pouvez utiliser un outil comme ngrok ou webhook.site. Ces outils vous permettent de voir à quoi ressemble le payload du webhook et de simuler des événements webhook en local avant de déployer votre application dans un environnement de production. Grâce à ces outils, vous pouvez vérifier que votre intégration webhook fonctionne correctement et traiter les éventuels problèmes dans un environnement local et contrôlé avant de passer en production.

Renvoyer le webhook d’une transaction

Si, pour une raison quelconque, vous ne recevez pas le webhook d’une transaction et que le délai des nouvelles tentatives est écoulé, nous mettons à votre disposition une API pour renvoyer le webhook de la transaction.
À utiliser avec précaution !
Comme cela peut conduire à traiter des transactions déjà terminées, assurez-vous d’avoir mis en place une validation appropriée lorsque vous utilisez cet endpoint.

Vérifier l’origine des événements

Comme votre URL webhook est accessible publiquement, vous devez vérifier que les événements proviennent bien de Blockradar et non d’un acteur malveillant. Il existe deux façons de vous assurer que les événements reçus sur votre URL webhook proviennent de Blockradar :
  1. Validation de la signature (recommandé)

Validation de la signature

Les événements envoyés par Blockradar portent l’en-tête x-blockradar-signature. La valeur de cet en-tête est une signature HMAC SHA512 du payload de l’événement, signée avec votre clé secrète. La signature de l’en-tête doit être vérifiée avant de traiter l’événement :

Checklist de mise en production

Maintenant que vous avez créé votre URL webhook, voici quelques moyens de garantir une expérience optimale :
  • Ajoutez l’URL webhook sur vos portefeuilles principaux depuis le tableau de bord Blockradar
  • Assurez-vous que votre URL webhook est accessible publiquement (les URL localhost ne peuvent pas recevoir d’événements)
  • Si vous utilisez .htaccess, pensez à ajouter le / final à l’URL
  • Testez votre webhook pour vérifier que vous recevez bien le corps JSON et que vous renvoyez une réponse HTTP 200 OK
  • Si votre fonction webhook comporte des tâches de longue durée, accusez d’abord réception du webhook en renvoyant un 200 OK avant d’exécuter ces tâches
  • Si nous ne recevons pas de réponse HTTP 200 OK de votre webhook, nous considérons la tentative comme échouée
  • Nous tenterons d’envoyer les webhooks 5 fois, avec un délai croissant entre chaque tentative, en commençant par 5 minutes et en augmentant de manière exponentielle jusqu’à 80 minutes. La durée totale de ces 5 tentatives sera d’environ 2 heures et 35 minutes.

Types d’événements

Voici les événements que nous émettons actuellement. Nous compléterons cette liste au fur et à mesure que nous prendrons en charge de nouvelles actions.

Frais de réseau dans les payloads de webhooks

Chaque webhook de transaction inclut deux champs qui décrivent les frais de réseau impliqués dans le traitement de la transaction : un résumé networkFee et un détail networkFees.

networkFee

Le total des frais de réseau payés par vos portefeuilles gérés par Blockradar pour ce flux de transaction, dans le token natif de la chaîne et en USD. C’est la valeur à utiliser pour répercuter le coût sur votre client.
networkFee est null quand l’événement ne porte aucun frais payé par vos portefeuilles. Le cas le plus courant est deposit.success, où le gas a été payé par le déposant. Ces frais restent visibles dans le champ gasFee de la transaction ; ce n’est simplement pas un coût que vous avez supporté.
Un événement withdraw.failed peut porter un networkFee non null. Si un retrait échoue sur la chaîne, le gas a tout de même été dépensé.

networkFees

Le détail vérifiable derrière le résumé. Chaque entrée correspond à un frais on-chain avec son propre hash de transaction, de sorte que chaque étape peut être vérifiée indépendamment sur un explorateur de blocs. Une seule action logique implique souvent plusieurs transactions de frais, par exemple alimenter une adresse de dépôt en gas, approuver un token puis effectuer le sweep. Le détail ci-dessous correspond au résumé networkFee ci-dessus, et ses entrées totalisent exactement ce montant.
Deux règles pour utiliser ces champs :
  1. Pour facturer votre client, utilisez networkFee. Il ne totalise que les entrées payées par vos portefeuilles (ADDRESS et MASTER_WALLET) et exclut tout ce qui est sponsorisé par Blockradar (PLATFORM et PROVIDER). Ne répercutez jamais les entrées sponsorisées sur vos clients.
  2. Le détail est un instantané au moment de l’envoi du webhook. Un frais enregistré après l’événement, par exemple un drainage du gas restant, apparaît lors des renvois du webhook et sur l’API des frais de réseau (GET /wallets/{walletId}/network-fees), qui est le registre en temps réel.

Exemples d’événements

Voici des exemples de payloads webhook pour certains des événements les plus courants :

Webhooks de transaction onramp

Blockradar émet un webhook de transaction unifié chaque fois que de la monnaie fiat est convertie et réglée en actif numérique. Cela s’applique que le paiement provienne d’un compte virtuel permanent ou d’un ordre de paiement Deposit Fiat.
Onramp Webhook
Utilisez data.id comme identifiant de la transaction onramp et traitez les événements de manière idempotente. La relation source identifie le rail d’origine :
  • data.virtualAccount est renseigné pour un paiement sur compte virtuel.
  • data.paymentOrder est renseigné pour un ordre de paiement Deposit Fiat.
Deposit Fiat peut également émettre des événements onramp.payment-order.* qui décrivent le cycle de vie de la ressource ordre de paiement. Ces événements complètent onramp.* ; ils ne remplacent pas le webhook de transaction. Consultez Webhooks Deposit Fiat.
Les événements deposit.* sont réservés aux dépôts crypto on-chain dont le type de transaction est DEPOSIT. Utilisez onramp.* pour le règlement fiat vers crypto et confirmez la finalisation avec onramp.success.

Liste complète des événements

Types et statuts de transaction

Types de transaction

Les types de transaction suivants sont utilisés dans les payloads de webhooks :

Statuts de transaction

Les statuts suivants indiquent l’état actuel d’une transaction :
Ces types et statuts de transaction sont utilisés dans les champs type et status des payloads de webhooks pour vous aider à comprendre quel type de transaction a eu lieu et quel est son état actuel.
Bon codage ! ❤️