Skip to main content

Contract Events & Webhooks

The ONE SDK lets you subscribe to on-chain contract events using webhooks. When a matching event is emitted, the Engine sends an HTTP POST to your configured endpoint with the decoded event data.

How It Works​

Contract emits Transfer event
        |
        v
  ONE Engine indexer detects the event
        |
        v
  Engine matches event against active webhooks
        |
        v
  HTTP POST to your webhook URL with event payload

createWebhook​

Register a new webhook subscription for contract events.

Method Signature​

client.createWebhook(params: CreateWebhookParams): Promise<ApiResponse<Webhook>>

CreateWebhookParams​

import type { CreateWebhookParams, WebhookEventType } from '@one_deploy/sdk';

interface CreateWebhookParams {
  url: string;                           // Your HTTPS endpoint
  eventType: WebhookEventType;           // Event category to subscribe to
  contractAddress?: string;              // Filter to a specific contract
  chainId?: number;                      // Filter to a specific chain
  eventName?: string;                    // Filter to a specific event name (e.g. 'Transfer')
  secret?: string;                       // Shared secret for HMAC signature verification
  metadata?: Record<string, unknown>;    // Custom metadata attached to the webhook
  active?: boolean;                      // Whether the webhook is active (default true)
}

WebhookEventType​

type WebhookEventType =
  | 'contract.event'        // Any event emitted by a contract
  | 'contract.transfer'     // ERC-20 / ERC-721 / ERC-1155 Transfer events
  | 'contract.approval'     // ERC-20 Approval events
  | 'contract.deploy'       // Contract deployment confirmations
  | 'transaction.confirmed' // Any transaction confirmation
  | 'transaction.failed';   // Any transaction failure

Webhook Response​

interface Webhook {
  id: string;                // Unique webhook ID
  url: string;
  eventType: WebhookEventType;
  contractAddress?: string;
  chainId?: number;
  eventName?: string;
  active: boolean;
  createdAt: string;         // ISO-8601
}

Examples​

Listen for ERC-20 Transfer Events​

import { useOneEngine } from '@one_deploy/sdk';

function SetupTransferWebhook() {
  const { client } = useOneEngine();

  async function subscribe() {
    const res = await client.createWebhook({
      url: 'https://api.myapp.com/webhooks/transfers',
      eventType: 'contract.transfer',
      contractAddress: '0xA0b8...3E7a',     // USDC contract
      chainId: 1,                            // Ethereum mainnet
      eventName: 'Transfer',
      secret: 'whsec_my_shared_secret_123',
    });

    if (res.success) {
      console.log('Webhook created:', res.data.id);
    } else {
      console.error('Failed:', res.error?.message);
    }
  }

  return <button onClick={subscribe}>Subscribe to USDC Transfers</button>;
}

Listen for All Events on a Contract​

Omit eventName to receive every event the contract emits:

const res = await client.createWebhook({
  url: 'https://api.myapp.com/webhooks/all-events',
  eventType: 'contract.event',
  contractAddress: '0x5566...7788',
  chainId: 137,
  secret: 'whsec_polygon_events',
});

Listen for Deployment Confirmations​

Get notified when any contract you deploy is confirmed:

const res = await client.createWebhook({
  url: 'https://api.myapp.com/webhooks/deploys',
  eventType: 'contract.deploy',
  secret: 'whsec_deploy_notifications',
});

Listen for Transaction Failures​

Monitor failed transactions across all contracts:

const res = await client.createWebhook({
  url: 'https://api.myapp.com/webhooks/failures',
  eventType: 'transaction.failed',
  chainId: 137,
  secret: 'whsec_failure_alerts',
});

Webhook Payload​

When an event matches, the Engine sends a POST request with the following JSON body:

interface WebhookPayload {
  id: string;                // Unique delivery ID
  webhookId: string;         // The webhook subscription ID
  eventType: WebhookEventType;
  timestamp: string;         // ISO-8601
  data: {
    chainId: number;
    contractAddress: string;
    transactionHash: string;
    blockNumber: number;
    eventName: string;       // e.g. 'Transfer'
    args: Record<string, unknown>; // Decoded event arguments
  };
}

Example payload for an ERC-20 Transfer:

{
  "id": "dlv_abc123",
  "webhookId": "whk_xyz789",
  "eventType": "contract.transfer",
  "timestamp": "2025-03-15T10:30:00.000Z",
  "data": {
    "chainId": 1,
    "contractAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "transactionHash": "0x1234...abcd",
    "blockNumber": 19500000,
    "eventName": "Transfer",
    "args": {
      "from": "0xSender...",
      "to": "0xRecipient...",
      "value": "1000000"
    }
  }
}

Verifying Webhook Signatures​

When you set a secret, the Engine includes an X-One-Signature header containing an HMAC-SHA256 signature of the request body. Always verify this in your handler to ensure the payload is authentic.

import crypto from 'node:crypto';

function verifyWebhookSignature(
  body: string,
  signature: string,
  secret: string,
): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected),
  );
}

// Express example
app.post('/webhooks/transfers', (req, res) => {
  const signature = req.headers['x-one-signature'] as string;
  const rawBody = JSON.stringify(req.body);

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

  const payload = req.body;
  console.log(`Transfer on chain ${payload.data.chainId}:`,
    payload.data.args.from, '->', payload.data.args.to,
    'amount:', payload.data.args.value,
  );

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

Managing Webhooks​

The Engine also provides methods to list, update, and delete webhooks:

// List all webhooks
const list = await client.getWebhooks();
// list.data -> Webhook[]

// Update a webhook (toggle active state)
const updated = await client.updateWebhook('whk_xyz789', {
  active: false,
});

// Delete a webhook
await client.deleteWebhook('whk_xyz789');

Node.js / Edge Runtime​

import { OneEngineClient } from '@one_deploy/sdk';

const client = new OneEngineClient({
  apiKey: process.env.ONE_API_KEY!,
  projectId: process.env.ONE_PROJECT_ID!,
});

const res = await client.createWebhook({
  url: 'https://api.myapp.com/webhooks/transfers',
  eventType: 'contract.transfer',
  contractAddress: '0xA0b8...3E7a',
  chainId: 1,
  eventName: 'Transfer',
  secret: 'whsec_server_side',
});

console.log('Webhook ID:', res.data.id);
tip

For the full webhooks API reference -- including retry policies, delivery logs, and batch subscriptions -- see the Webhooks API Reference.

Next Steps​