Webhook Fundamentals - ChainStream

Beta — This feature is currently in beta. API may be subject to changes.

This document introduces the working principles, configuration methods, and best practices for ChainStream Webhooks, helping you implement real-time on-chain event delivery.

Webhook functionality is available to all users.

How It Works

Data Flow

Core Features

Feature	Description
Real-time Delivery	Millisecond-level delivery after event trigger
Reliable Delivery	Auto-retry on failure
Signature Verification	HMAC signature anti-forgery
Filter Rules	Support event type filtering

Supported Event Types

Webhook currently supports the following event types (channels):

Channel	Description	Typical Use
`sol.token.created`	Solana new token creation	New token discovery, early opportunities
`sol.token.migrated`	Solana token graduation/migration	Track tokens graduating from Pump.fun and similar platforms

More event types are in development. Stay tuned!

Create Webhook Endpoint

API Endpoint

POST /v1/webhook/endpoint
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

Request Parameters

Parameter	Type	Required	Description
`url`	string	Yes	Webhook callback URL (must be HTTPS)
`channels`	array	Yes	List of event types to subscribe to
`description`	string	No	Endpoint description
`disabled`	boolean	No	Whether disabled, default false
`filterTypes`	array	No	Filter types
`metadata`	object	No	Custom metadata
`rateLimit`	integer	No	Rate limit

Request Example

{
  "url": "https://your-server.com/webhook",
  "channels": ["sol.token.created", "sol.token.migrated"],
  "description": "Monitor new tokens and graduated tokens"
}

Response Example

{
  "id": "ep_abc123",
  "url": "https://your-server.com/webhook",
  "channels": ["sol.token.created", "sol.token.migrated"],
  "description": "Monitor new tokens and graduated tokens",
  "disabled": false
}

Webhook Notification Format

Webhook notification data structure is consistent with WebSocket push.

New Token Created (sol.token.created)

{
  "channel": "sol.token.created",
  "timestamp": 1706947200000,
  "data": {
    "a": "6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN",
    "n": "Example Token",
    "s": "EXT",
    "dec": 9,
    "cts": 1706947200000,
    "lf": {
      "pa": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
      "pf": "pump_fun",
      "pn": "Pump.fun"
    }
  }
}

Field Descriptions:

Field	Description
`a`	Token address
`n`	Token name
`s`	Token symbol
`dec`	Decimals
`cts`	Created timestamp (milliseconds)
`lf.pa`	Launch platform program address
`lf.pf`	Protocol family
`lf.pn`	Protocol name

Token Graduated (sol.token.migrated)

{
  "channel": "sol.token.migrated",
  "timestamp": 1706947200000,
  "data": {
    "a": "6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN",
    "n": "Example Token",
    "s": "EXT",
    "cts": 1706947200000,
    "lf": {
      "pa": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
      "pf": "pump_fun",
      "pn": "Pump.fun"
    },
    "mt": {
      "pa": "675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8",
      "pf": "raydium",
      "pn": "Raydium"
    }
  }
}

Additional Fields:

Field	Description
`mt.pa`	Migration target platform program address
`mt.pf`	Migration target protocol family
`mt.pn`	Migration target protocol name

Webhook URL Requirements

Requirement	Description
✅ HTTPS	Must use HTTPS protocol
✅ Publicly Accessible	URL must be accessible from public internet
✅ 2xx Response	Must return 2xx status code for success
✅ Response Time	Should respond within 5 seconds
✅ Idempotent Handling	Must handle duplicate requests

Security Verification

Get Webhook Secret

After creating an endpoint, get the secret via this API:

GET /v1/webhook/endpoint/{id}/secret

Response:

{
  "secret": "whsec_abcdXXX"
}

Signature Verification

Each Webhook request includes signature headers for verifying request origin:

X-Webhook-Signature: <signature>
X-Webhook-Timestamp: <timestamp>

Verification Flow

Code Examples

Node.js
Python
Go

const crypto = require('crypto');

function verifyWebhook(req, secret) {
  const signature = req.headers['x-webhook-signature'];
  const timestamp = req.headers['x-webhook-timestamp'];
  const body = JSON.stringify(req.body);
  
  // Check timestamp (5-minute window)
  const now = Date.now();
  if (Math.abs(now - parseInt(timestamp)) > 300000) {
    return false;
  }
  
  // Calculate signature
  const message = `${timestamp}.${body}`;
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(message)
    .digest('hex');
  
  // Safe comparison
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

import hmac
import hashlib
import time

def verify_webhook(request, secret):
    signature = request.headers.get('X-Webhook-Signature')
    timestamp = request.headers.get('X-Webhook-Timestamp')
    body = request.get_data(as_text=True)
    
    # Check timestamp (5-minute window)
    now = int(time.time() * 1000)
    if abs(now - int(timestamp)) > 300000:
        return False
    
    # Calculate signature
    message = f"{timestamp}.{body}"
    expected_signature = hmac.new(
        secret.encode(),
        message.encode(),
        hashlib.sha256
    ).hexdigest()
    
    # Safe comparison
    return hmac.compare_digest(signature, expected_signature)

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "strconv"
    "time"
)

func verifyWebhook(signature, timestamp, body, secret string) bool {
    // Check timestamp
    ts, _ := strconv.ParseInt(timestamp, 10, 64)
    now := time.Now().UnixMilli()
    if abs(now-ts) > 300000 {
        return false
    }
    
    // Calculate signature
    message := timestamp + "." + body
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte(message))
    expected := hex.EncodeToString(mac.Sum(nil))
    
    return hmac.Equal([]byte(signature), []byte(expected))
}

Manage Webhook Endpoints

List Endpoints

GET /v1/webhook/endpoint

Query Parameters:

Parameter	Type	Description
`limit`	integer	Items per page (1-100, default 100)
`iterator`	string	Pagination iterator
`order`	string	Sort order (ascending/descending)

Get Endpoint Details

GET /v1/webhook/endpoint/{id}

Update Endpoint

PATCH /v1/webhook/endpoint

{
  "endpointId": "ep_abc123",
  "channels": ["sol.token.created"],
  "description": "Monitor new tokens only"
}

Delete Endpoint

DELETE /v1/webhook/endpoint/{id}

Rotate Secret

POST /v1/webhook/endpoint/{id}/secret/rotate

Best Practices

✅ Fast Response

# Recommended: Respond first, process later
@app.route('/webhook', methods=['POST'])
def webhook():
    # Verify signature
    if not verify_webhook(request, SECRET):
        return "Invalid signature", 401
    
    # Put in queue for async processing
    queue.put(request.json)
    
    # Return 200 immediately
    return "OK", 200

✅ Idempotency Handling

Each event contains a unique identifier. Record processed events on your server:

# Use Redis to record processed events
def process_webhook(event):
    event_id = f"{event['channel']}:{event['data']['a']}:{event['timestamp']}"
    
    # Check if already processed
    if redis.exists(f"processed:{event_id}"):
        return {"status": "already_processed"}
    
    # Process event
    handle_event(event)
    
    # Mark as processed (TTL 24 hours)
    redis.setex(f"processed:{event_id}", 86400, "1")
    
    return {"status": "ok"}

✅ Security

Always Verify Signature

Verify signature for every request

Use HTTPS

Ensure transport security

Rotate Secret Regularly

Recommended every 90 days

Protect Sensitive Data

Don’t log sensitive data

✅ Reliability

Implement Idempotency

Handle duplicate requests

Message Queue Buffer

Use queues for async processing

Reasonable Timeout

Avoid long blocking

Comprehensive Logging

Log key information for troubleshooting

FAQ

Not receiving Webhook requests?

Troubleshooting steps:

Confirm URL is accessible — Test if URL is reachable from public internet
Check HTTPS — Must use a valid SSL certificate
Check endpoint status — Confirm disabled is not true
Check channels — Confirm subscribed to correct event types

Receiving duplicate events?

This may be caused by retry mechanism. Implement idempotency handling:

Use unique event identifier (channel + token address + timestamp)
Check if already processed when receiving requests
Use cache with TTL (like Redis) for storage

How to test Webhooks?

Use ngrok to expose local service
Create Webhook endpoint pointing to ngrok URL
Wait for real events to trigger, or use test environment
Check local service logs

API Endpoint Summary

Function	Endpoint
List Endpoints	`GET /v1/webhook/endpoint`
Create Endpoint	`POST /v1/webhook/endpoint`
Update Endpoint	`PATCH /v1/webhook/endpoint`
Get Endpoint Details	`GET /v1/webhook/endpoint/{id}`
Delete Endpoint	`DELETE /v1/webhook/endpoint/{id}`
Get Secret	`GET /v1/webhook/endpoint/{id}/secret`
Rotate Secret	`POST /v1/webhook/endpoint/{id}/secret/rotate`

WebSocket API

Real-time data subscription

Endpoint API Reference

Complete API documentation

Frameworks

Tutorials

​How It Works

​Data Flow

​Core Features

​Supported Event Types

​Create Webhook Endpoint

​API Endpoint

​Request Parameters

​Request Example

​Response Example

​Webhook Notification Format

​New Token Created (sol.token.created)

​Token Graduated (sol.token.migrated)

​Webhook URL Requirements

​Security Verification

​Get Webhook Secret

​Signature Verification

​Verification Flow

​Code Examples

​Manage Webhook Endpoints

​List Endpoints

​Get Endpoint Details

​Update Endpoint

​Delete Endpoint

​Rotate Secret

​Best Practices

​✅ Fast Response

​✅ Idempotency Handling

​✅ Security

Always Verify Signature

Use HTTPS

Rotate Secret Regularly

Protect Sensitive Data

​✅ Reliability

Implement Idempotency

Message Queue Buffer

Reasonable Timeout

Comprehensive Logging

​FAQ

​API Endpoint Summary

​Related Documentation

WebSocket API

Endpoint API Reference

How It Works

Data Flow

Core Features

Supported Event Types

Create Webhook Endpoint

API Endpoint

Request Parameters

Request Example

Response Example

Webhook Notification Format

New Token Created (sol.token.created)

Token Graduated (sol.token.migrated)

Webhook URL Requirements

Security Verification

Get Webhook Secret

Signature Verification

Verification Flow

Code Examples

Manage Webhook Endpoints

List Endpoints

Get Endpoint Details

Update Endpoint

Delete Endpoint

Rotate Secret

Best Practices

✅ Fast Response

✅ Idempotency Handling

✅ Security

✅ Reliability

FAQ

API Endpoint Summary

Related Documentation