Webhooks

Webhooks allow your system to receive real-time notifications from Kepler when specific events occur on the blockchain. This page details how to configure filters, process payloads, and verify the sec

Event Filtering Options

When configuring a webhook, you can filter which events trigger a notification. You can use a combination of three criteria.

ℹ️ Note If multiple filters are set, all conditions must match (AND logic) for the webhook to be triggered. If you set both an address and an identifier, only events matching both will trigger the webhook.

Filter	Description	Example
address	The smart contract address that emitted the event. Must be an exact match.	erd1qqqq...
identifier	The event identifier/name. Must be an exact match.	transfer, swap
topic	The first topic of the event (decoded from base64). Must be an exact match.	claimed

Configuration Rules

• Requirement: At least one filter (address, identifier, or topic) is mandatory.

• Decoding: Topics in MultiversX events are base64-encoded. The filter matches against the decoded value of the first topic.

Common Examples

Configuration	Result
address: erd1qqq...abc	Receives all events from this specific address.
identifier: transfer	Receives all transfer events from any address.
address: erd1qqq...abc identifier: distribute	Receives only distribute events from the specific address.

---

Webhook Delivery

When an event matches your filters, Kepler sends an HTTP POST request to your configured URL.

The Payload

The request body is a JSON object containing the event details and a timestamp.

{
  "event": {
    "address": "erd1qqqqqqqqqqqqqpgqjhn0rrta3hceyguqlmkqgklxc0eh0r5rl3tsv6a9k0",
    "identifier": "distribute",
    "topics": [
      "ZGlzdHJpYnV0ZWQ=",
      "AAAAAAAAAAAFAPWuOkANricr0lRon9WkT4jj8pSeV4c=",
      "Q09MUy05ZDkxYjc=",
      "iscjBInoAAA="
    ],
    "data": "",
    "txHash": "2151f16aa3a491d5979d16d6e6ad128da9851d3d65bf63cf226d8083432a201b"
  },
  "timestamp": 1706540400,
  "webhook": "550e8400-e29b-41d4-a716-446655440000"
}

Markdown

Field	Type	Description
event.address	string	The smart contract address that emitted the event.
event.identifier	string	The event identifier/name.
event.topics	string[]	Array of base64-encoded topics.
event.data	string	Base64-encoded event data (may be empty).
event.txHash	string	The transaction hash that triggered the event.
timestamp	number	Unix timestamp (seconds) of webhook dispatch.
webhook	string	Your webhook's unique identifier.

Headers

Header	Value	Description
Content-Type	application/json	The media type of the body.
X-Signature	Hex-string	Important: The cryptographic signature for verification.
User-Agent	ProjectX-Kepler/{version}	Identifies the sender.

---

Delivery Lifecycle

Expected Response

Your endpoint must return a status code in the 2xx range (e.g., 200 OK) to acknowledge receipt. The response body is ignored.

⚠️ Warning

Your server must respond within 10 seconds. If the request times out, it is treated as a failure and will be retried.

Retry Mechanism

If delivery fails (network error, timeout, or non-2xx status), Kepler retries automatically.

• Max Retries: 3 attempts (4 total requests).

• Strategy: Progressive backoff (5s, 10s, 15s).

Example Timeline:

1. T+0s: Initial attempt (Fails)

2. T+5s: Retry 1 (Fails)

3. T+15s: Retry 2 (Fails)

4. T+30s: Final Retry

---

Security & Verification

To ensure requests originate from Kepler and haven't been tampered with, you must verify the X-Signature header.

Verification Logic

1. Serialize: Read the raw request body as a string.

2. Verify: Use the MultiversX message signing algorithm (Ed25519) to verify the body against the signature.

3. Public Key: Use the official Kepler signing address below.

Kepler Public Signing Address:

Plaintext

erd1c0mj9ctdg0xv872j4v3rs8ygcz2tdx7mtxffawj9trxfkvwg0njq7uzp58

Code Examples

TypeScript / JavaScript

import { Address, Message, MessageComputer } from '@multiversx/sdk-core';

const SIGNING_ADDRESS = 'erd1c0mj9ctdg0xv872j4v3rs8ygcz2tdx7mtxffawj9trxfkvwg0njq7uzp58';

function verifyWebhookSignature(payload: string, signature: string): boolean {
  const messageComputer = new MessageComputer();
  
  const message = new Message({
    data: new Uint8Array(Buffer.from(payload)),
    address: Address.fromBech32(SIGNING_ADDRESS),
    signature: Buffer.from(signature, 'hex'),
  });

  return messageComputer.verifyMessage(message);
}

// Express.js usage
app.post('/webhook', express.text({ type: 'application/json' }), (req, res) => {
  const payload = req.body; // Ensure this is the RAW string body
  const signature = req.headers['x-signature'] as string;

  if (!verifyWebhookSignature(payload, signature)) {
    return res.status(401).send('Invalid signature');
  }

  res.status(200).send('OK');
});

Python

from multiversx_sdk import Address, MessageComputer, Message

SIGNING_ADDRESS = 'erd1c0mj9ctdg0xv872j4v3rs8ygcz2tdx7mtxffawj9trxfkvwg0njq7uzp58'

def verify_webhook_signature(payload: str, signature: str) -> bool:
    message_computer = MessageComputer()
    
    message = Message(
        data=payload.encode('utf-8'),
        address=Address.new_from_bech32(SIGNING_ADDRESS),
        signature=bytes.fromhex(signature)
    )
    
    return message_computer.verify_message(message)

---

Best Practices

• Idempotency: In rare network conditions, you may receive the same webhook twice. Always use the event.txHash as a unique key to prevent processing the same event multiple times.

• Async Processing: Return a 200 OK immediately, then process the data asynchronously (e.g., send it to a queue). This prevents timeouts.

• Security: Always use HTTPS. Validate the timestamp field (e.g., ensure it is within the last 5 minutes) to prevent replay attacks.

---

Quick Start: Receive Your First Webhook

Follow this guide to set up a local webhook receiver, expose it to the internet, and trigger a test event from Kepler.

---

Prerequisites

• A Kepler account.

• Node.js installed on your machine.

• A tool to tunnel local ports to the internet (e.g., ngrok).

---

Step 1: Create a Simple Receiver

Create a file named server.js and paste the following code. This sets up a basic Express server that logs incoming webhooks to your console.

const express = require('express');
const app = express();
const port = 3000;

// Middleware to parse JSON bodies
app.use(express.json());

app.post('/webhook', (req, res) => {
  // 1. Log the incoming event
  console.log('🔔 Webhook Received!');
  console.log('Event:', req.body.event.identifier);
  console.log('TxHash:', req.body.event.txHash);

  // 2. Respond quickly with 200 OK
  res.status(200).send('Received');
});

app.listen(port, () => {
  console.log(`🚀 Receiver running on http://localhost:${port}`);
});

Install dependencies and start the server:

Bash

npm install express
node server.js

---

Step 2: Expose Your Server

Since Kepler cannot reach your localhost directly, use a tunneling service to create a public URL.

Bash

# If using ngrok
ngrok http 3000

Copy the HTTPS URL generated by ngrok (e.g., https://a1b2-c3d4.ngrok-free.app). Your full webhook URL will be: https://a1b2-c3d4.ngrok-free.app/webhook

---

Step 3: Configure Kepler

1. Log in to your Kepler dashboard and navigate to Webhooks.

2. Click Create Webhook.

3. URL: Paste your ngrok URL (ensure it ends with /webhook).

4. Filters: Set up a filter to reduce noise. For testing, you might want to track a common token transfer.

   • Identifier: transfer

   • (Leave Address and Topic empty to catch all transfers for now)

ℹ️ Tip Start with broad filters (like just an identifier) to ensure your connection works, then narrow them down with specific address or topic filters later.

---

Step 4: Test and Verify

1. Trigger an action on the blockchain (or wait for a live event that matches your filter).

2. Check your terminal running server.js. You should see:

Plaintext

🔔 Webhook Received!
Event: transfer
TxHash: 2151f16aa3a491d5979d16d6e6ad128da9851d3d65bf63cf226d8083432a201b

1. Check the Kepler dashboard. The webhook status should show 200 OK.

---

What's Next?

Now that you are receiving events:

• Secure your endpoint: Implement Signature Verification.

• Handle logic: Parse the topics array to decode transfer amounts and recipients.

• Go to production: Deploy your Node.js script to a cloud provider (AWS, Heroku, DigitalOcean).