Set a webhook for a smart contract


This guide is designed to walk you through setting up Webhooks to seamlessly receive events related to a smart contract on the blockchain. Following these steps lets you stay updated on various events and activities occurring within a smart contract, ensuring you're always informed about the latest changes.


  • 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.

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 These platforms provide temporary callback URLs that you can use to receive webhook payloads for testing purposes.

Call the Create Webhook Endpoint

After obtaining your callback URL and authorisation token, it's time to call the Create Webhook for a smart contract endpoint provided by Overledger. This endpoint enables you to register your callback URL and specify the smart contract for which you want to receive notifications for any event the contract emits. You can find the create webhook endpoint under our API references Create Webhook for Smart Contract Events

When specifying the smartContractId, please make sure that you provide the appropriate identifier or address that uniquely identifies the smart contract on the blockchain.

curl --request POST \
     --url \
     --header 'API-Version: 3.0.0' \
     --header 'Authorization: Bearer token' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     --data '
  "location": {
    "technology": "ethereum",
    "network": "ethereum sepolia testnet"
  "callbackUrl": "",
  "smartContractId": "0xpo98iuytgbnmjkoi87ytghjiu"

Upon successfully creating your smart contract 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.

  "createdAt": "1678282471",
  "webhookId": "90fd50e7-9bae-4bb0-85e1-6db21180b53d",
  "callbackUrlStatus": "ACTIVE",
  "location": {
    "technology": "ethereum",
    "network": "ethereum goerli testnet"
  "callbackUrl": "",
  "smartContractId": "0xpo98iuytgbnmjkoi87ytghjiu",
  "updatedAt": "1678282471"

Furthermore, setting up this webhook ensures you will receive updates on all events the specified smart contract directly to the provided callback URL. This lets you stay informed about every change and activity related to the designated smart contract.

Furthermore, by setting up this webhook, you will receive updates directly to the provided callbackUrlregarding all events emitted by the specified smartContractId.

Receiving a callback

When an event is emitted by the specified smartContractId, then your callbackUrl will receive a message such as this:

  "type": "smartContractEvent",
  "webhookId": "6c964253-4b10-43a5-a812-9b30e92275a3",
  "location": {
    "technology": "ethereum",
    "network": "polygon mumbai testnet"
  "smartContractEventUpdateDetails": {
    "smartContractId": "0x8590d37d55049de2555f0f9541325e7fe6b19b17",
    "nativeData": {
      "removed": false,
      "logIndex": 0,
      "transactionIndex": 0,
      "transactionHash": "0xde2bbf9704d726ff395eb78217e9acb226b0ecb0b609021cccd7e67d99763db2",
      "blockHash": "0x6d1a13d15fd0a90f361d3e368830bbe45c628382c4533d10f1a23ae699c781cc",
      "blockNumber": "0x28b2471",
      "address": "0x8590d37d55049de2555f0f9541325e7fe6b19b17",
      "data": "0x0000000000000000000000001789d90438333751fdcca0d03d8952168b99ef02",
      "topics": [