Passer au contenu principal

​
Introduction

Generalement, lorsque vous faites une requete a un endpoint API, vous vous attendez a obtenir une reponse quasi immediate. Cependant, certaines requetes peuvent prendre beaucoup de temps a traiter, ce qui peut entrainer des erreurs de timeout. Afin d’eviter une erreur de timeout, une reponse en attente est retournee. Puisque vos enregistrements doivent etre mis a jour avec l’etat final de la requete, vous devez soit :
  1. Faire une requete pour une mise a jour (communement appelee polling) ou,
  2. Ecouter les evenements en utilisant une URL webhook.
Conseil Utile
Nous recommandons d’utiliser les webhooks pour fournir de la valeur a vos clients plutot que d’utiliser des callbacks ou le polling. Avec les callbacks, nous n’avons pas de controle sur ce qui se passe du cote du client. Vous non plus. Les callbacks peuvent echouer si la connexion reseau sur l’appareil d’un client echoue ou est faible ou si l’appareil s’eteint apres une transaction.

​
Polling vs Webhooks

Le polling necessite de faire une requete GET a intervalles reguliers pour obtenir le statut final d’une requete. Par exemple, lorsque vous attribuez une adresse a un client pour les depots, vous continuez a faire une requete pour les transactions liees a l’adresse jusqu’a ce que vous en trouviez une. Avec les webhooks, le serveur de ressources, Blockradar dans ce cas, envoie des mises a jour a votre serveur lorsque le statut de votre requete change. Le changement de statut d’une requete est appele un evenement. Vous ecouterez typiquement ces evenements sur un endpoint POST appele votre URL webhook. Le tableau ci-dessous met en evidence quelques differences entre le polling et les webhooks :
PollingWebhooks
Mode de mise a jourManuelAutomatique
Limitation de debitOuiNon
Impacte par le scalingOuiNon

​
Creer une URL webhook

Une URL webhook est simplement un endpoint POST vers lequel un serveur de ressources envoie des mises a jour. L’URL doit analyser une requete JSON et retourner un 200 OK : 
// Using Express
app.post("/my/webhook/url", function(req, res) {
    // Retrieve the request's body
    const event = req.body;
    // Do something with event
    res.send(200);
});
Lorsque votre URL webhook recoit un evenement, elle doit analyser et accuser reception de l’evenement. Accuser reception d’un evenement signifie retourner un 200 OK dans l’en-tete HTTP. Sans un 200 OK dans l’en-tete de reponse, nous continuerons a envoyer des evenements pendant les 2 heures et 35 minutes suivantes :
  • Nous tenterons d’envoyer les webhooks 5 fois avec un delai croissant entre chaque tentative, en commencant par 5 minutes et en augmentant de maniere exponentielle jusqu’a 80 minutes. La duree totale pour ces 5 tentatives sera d’environ 2 heures et 35 minutes.
Evitez les taches de longue duree
Si vous avez des taches de longue duree dans votre fonction webhook, vous devriez accuser reception de l’evenement avant d’executer les taches de longue duree. Les taches de longue duree entraineront un timeout de requete et une reponse d’erreur automatique de votre serveur. Sans une reponse 200 OK, nous reessayons comme decrit dans le paragraphe ci-dessus.

​
Tester les Webhooks Localement

Pendant le developpement, vous pouvez configurer votre URL webhook dans votre environnement de portefeuille principal TEST vers une adresse locale, telle que http://localhost ou 127.0.0.1. Pour exposer votre serveur local a Internet a des fins de test, envisagez d’utiliser un outil comme ngrok ou webhook.site. Ces outils vous permettent de voir a quoi ressemble le payload webhook et de simuler des evenements webhook localement avant de deployer votre application dans un environnement de production. En utilisant ces outils, vous pouvez vous assurer que votre integration webhook fonctionne correctement et gerer tous les problemes dans un environnement local et controle avant de passer a la production.

​
Renvoyer le Webhook de Transaction

Dans le cas ou pour une raison quelconque vous ne recevez pas le webhook de transaction et que le temps de backoff est ecoule, nous avons fourni une API que vous pouvez utiliser pour renvoyer un webhook de transaction
Utilisez avec precaution !
Cela peut conduire au traitement de transactions deja completees, assurez-vous d’avoir une validation appropriee en place lors de l’utilisation de cet endpoint.
curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/transactions/webhooks/resend \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "id": "TRANSACTION_ID"
}'

​
Verifier l’origine de l’evenement

Puisque votre URL webhook est publiquement accessible, vous devez verifier que les evenements proviennent de Blockradar et non d’un acteur malveillant. Il existe deux facons de s’assurer que les evenements vers votre URL webhook proviennent de Blockradar :
  1. Validation de signature (recommande)

​
Validation de signature

Les evenements envoyes depuis Blockradar portent l’en-tete x-blockradar-signature. La valeur de cet en-tete est une signature HMAC SHA512 du payload de l’evenement signee en utilisant votre cle secrete. La verification de la signature de l’en-tete doit etre effectuee avant de traiter l’evenement : 
const crypto = require('crypto');
const apiKey = process.env.WALLET_API_KEY;
// Using Express
app.post("/my/webhook/url", function(req, res) {
    //validate event
    const hash = crypto.createHmac('sha512', apiKey).update(JSON.stringify(req.body)).digest('hex');
    if (hash == req.headers['x-blockradar-signature']) {
    // Retrieve the request's body
    const event = req.body;
    // Do something with event
    }
    res.send(200);
});

​
Checklist de Mise en Production

Maintenant que vous avez cree avec succes votre URL webhook, voici quelques facons d’assurer une experience agreable :
  • Ajoutez l’URL webhook sur vos portefeuilles principaux sur le tableau de bord Blockradar
  • Assurez-vous que votre URL webhook est publiquement accessible (les URL localhost ne peuvent pas recevoir d’evenements)
  • Si vous utilisez .htaccess, n’oubliez pas d’ajouter le / final a l’URL
  • Testez votre webhook pour vous assurer que vous obtenez le corps JSON et retournez une reponse HTTP 200 OK
  • Si votre fonction webhook a des taches de longue duree, vous devriez d’abord accuser reception du webhook en retournant un 200 OK avant de proceder aux taches de longue duree
  • Si nous n’obtenons pas une reponse HTTP 200 OK de vos webhooks, nous la signalons comme une tentative echouee
  • Nous tenterons d’envoyer les webhooks 5 fois avec un delai croissant entre chaque tentative, en commencant par 5 minutes et en augmentant de maniere exponentielle jusqu’a 80 minutes. La duree totale pour ces 5 tentatives sera d’environ 2 heures et 35 minutes.

​
Types d’evenements

Voici les evenements que nous declenchons actuellement. Nous ajouterons d’autres a cette liste a mesure que nous nous connecterons a plus d’actions a l’avenir.

​
Exemples d’Evenements

Voici des exemples de payloads webhook pour certains des evenements les plus courants : 
{
    "event": "deposit.success",
    "data": {
        "id": "6d2f9646-cae4-48a5-8bfe-1f9379868d4f",
        "reference": "LSk5RLfSrR",
        "senderAddress": "0x2455eC6700092991Ce0782365A89d5Cd89c8Fa22",
        "recipientAddress": "0xe1037B45b48390285e5067424053fa35c478296b",
        "amount": "10.0",
        "amountPaid": "10.0",
        "fee": null,
        "currency": "USD",
        "blockNumber": 6928760,
        "blockHash": "0x5f2e0ed782752b9559e7a3d89c0fb9f6706e4866e74ba7a434cf933bb3f02a2b",
        "hash": "0x94c733496df59c15e5a489f20374096bba31166a8e149ceea4d410e3e5821357",
        "confirmations": 6,
        "confirmed": true,
        "gasPrice": "1201381238",
        "gasUsed": "62159",
        "gasFee": "0.000074676656372842",
        "status": "SUCCESS",
        "type": "DEPOSIT",
        "note": null,
        "amlScreening": {
            "provider": "ofac",
            "status": "success",
            "message": "Address is not sanctioned"
        },
        "network": "testnet",
        "chainId": 11155111,
        "metadata": {
            "user_id": 1
        },
        "createdAt": "2024-10-23T11:19:58.451Z",
        "updatedAt": "2024-10-23T11:19:58.451Z",
        "asset": {
            "id": "fe04a28c-c615-4e41-8eda-f84c862864f5",
            "name": "USDC Coin",
            "symbol": "USDC",
            "decimals": 6
        },
        "address": {
            "id": "0a69c48a-6c6f-422c-bd6a-70de3306a3ac",
            "address": "0xe1037B45b48390285e5067424053fa35c478296b",
            "name": "Customer 1"
        },
        "blockchain": {
            "id": "85ffc132-3972-4c9e-99a5-5cf0ccb688bf",
            "name": "ethereum",
            "symbol": "eth",
            "slug": "ethereum"
        },
        "wallet": {
            "id": "d236a191-c1d4-423c-a439-54ce6542ca41",
            "name": "Ethereum Master Wallet",
            "address": "0x947514e4B803e312C312da0F1B41fEDdbe15ae7a"
        }
    }
}

​
Types d’Evenements Disponibles

EvenementDescription
deposit.processingUn depot est en cours de traitement
deposit.successUn depot a ete traite avec succes
deposit.failedUn depot a echoue
deposit.cancelledUn depot a ete annule
withdraw.processingUn retrait est en cours de traitement
withdraw.successUn retrait a ete traite avec succes
withdraw.failedUn retrait a echoue
withdraw.cancelledUn retrait a ete annule
swap.successUn swap a ete execute avec succes
swap.failedUn swap a echoue
signed.successUne transaction signee a ete completee avec succes
signed.failedUne transaction signee a echoue
Les payloads webhook complets incluent des informations detaillees sur les transactions, actifs, blockchains et portefeuilles. Consultez les onglets d’exemples ci-dessus pour les structures de payload completes.


Bon codage !