Set a webhook for an account

Introduction

This guide is designed to walk you through setting up webhooks to receive event-related notifications relating to an account on the blockchain. Following these steps, you can stay updated on various events and activities occurring within an account, ensuring you're always informed about the latest changes.

Prerequisites

  • Obtain an authorization token
    You must obtain an authorisation token to interact with Overledger's API and call any endpoint. This token will authenticate your requests and grant you access to the necessary endpoints. Please follow the authentication process provided by Overledger to get your authorisation token.
  • Select an account that you wish to monitor

Set up a callback URL

Before you can start receiving updates via Webhooks from Overledger, you need to establish a callback URL. This URL will serve as the endpoint where Overledger will send event notifications. You have two options for setting up your callback URL:

  • Option 1: Create a callback URL on your server. Ensure your server has a publicly accessible endpoint to receive incoming HTTP requests. You can set up a callback URL using your server's domain.
  • Option 2: Use an existing service: If you don't have your own server or prefer not to set up a callback URL manually, you can utilise services like Webhook.site. These platforms provide temporary callback URLs that you can use to receive webhook payloads for testing purposes.

Call the create webhook endpoint - add request

After obtaining your callback URL and authorisation token, it's time to call the Create Webhook for an account endpoint provided by Overledger. This endpoint enables you to register your callback URL and specify the blockchain account for which you want to receive notifications upon updates. You can find the create webhook endpoint under our API references Create Webhook for Account Updates

When specifying the accountId, please make sure that you provide the identifier for the specific blockchain account you wish to monitor. For example, in Ethereum, the accountId would typically be the address of the Ethereum account.

curl --request POST \
     --url https://api.sandbox.overledger.io/api/webhooks/accounts \
     --header 'API-Version: 3.0.0' \
     --header 'Authorization: Bearer token' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "accountId": "0xpo98iuytgbnmjkoi87ytghjiu",
  "location": {
    "technology": "ethereum",
    "network": "ethereum sepolia testnet"
  },
  "callbackUrl": "https://www.example.com"
}
'

Upon successfully creating your account webhook, you will receive a webhookId as part of the response object. It is imperative to store and retain this webhookId for future management and utilisation of your webhook.

{
  "accountId": "0xpo98iuytgbnmjkoi87ytghjiu",
  "createdAt": "1678282471",
  "webhookId": "12a13ee9-ac7e-4d73-8317-9713e1638d2c",
  "callbackUrlStatus": "ACTIVE",
  "location": {
    "technology": "ethereum",
    "network": "ethereum sepolia testnet"
  },
  "callbackUrl": "http://www.example.com",
  "updatedAt": "1678282471"
}

Furthermore, by setting up this webhook, you will receive updates directly to the provided callbackUrlregarding all transactions sent to or received by the specified blockchain accountId.

Receiving a callback

When a transaction is sent to or received by the specified blockchain accountId, then your callbackUrl will receive a message such as this:

{  
  "type": "account",  
  "webhookId": "20f6ce08-04b4-4ce4-94eb-e2304a0737af",  
  "accountId": "0x282f70d5af34aedaac479b12a08e189bbee83066",  
  "location": {  
    "technology": "ethereum",  
    "network": "polygon mumbai testnet"  
  },  
  "transactionId": "0xd65c16e476a5ad5fa89ffe14512bd7984e575a4370ac86ccfb88202da20f9262"  
}

To find out more information about the transaction that triggered this callback, you will need to search for the given transactionId, as explained here .