Webhooks API

The Webhooks API provides 7 methods for managing webhook subscriptions. Webhooks allow your application to receive real-time notifications when events occur (transactions, swaps, order completions, etc.).

Methods

Method	Parameters	Returns	Description
listWebhooks()	--	ApiResponse<Webhook[]>	Lists all webhooks configured for the current project.
getWebhook(webhookId)	webhookId: string	ApiResponse<Webhook>	Returns details for a single webhook.
createWebhook(input)	input: CreateWebhookInput	ApiResponse<Webhook>	Creates a new webhook subscription.
updateWebhook(webhookId, input)	webhookId: string, input: UpdateWebhookInput	ApiResponse<Webhook>	Updates an existing webhook's configuration.
deleteWebhook(webhookId)	webhookId: string	ApiResponse<{ deleted: boolean }>	Deletes a webhook subscription.
getWebhookDeliveries(webhookId, options?)	webhookId: string, options?: DeliveryListOptions	ApiResponse<WebhookDelivery[]>	Returns delivery history for a webhook.
testWebhook(webhookId)	webhookId: string	ApiResponse<WebhookDelivery>	Sends a test payload to the webhook endpoint.

Types

Webhook

interface Webhook {
  id: string;
  /** Project this webhook belongs to. */
  projectId: string;
  /** HTTPS URL that receives POST requests. */
  url: string;
  /** Events this webhook subscribes to. */
  events: WebhookEventType[];
  /** Secret used to sign payloads (HMAC-SHA256). */
  secret: string;
  /** Whether the webhook is active. */
  active: boolean;
  /** Optional description. */
  description?: string;
  /** Number of consecutive failures. Webhook is auto-disabled after 10. */
  failureCount: number;
  createdAt: string;
  updatedAt: string;
}

WebhookEventType

type WebhookEventType =
  | 'transaction.confirmed'
  | 'transaction.failed'
  | 'swap.completed'
  | 'swap.failed'
  | 'onramp.completed'
  | 'onramp.failed'
  | 'offramp.completed'
  | 'offramp.failed'
  | 'bridge.completed'
  | 'bridge.failed'
  | 'ai_order.created'
  | 'ai_order.completed'
  | 'ai_order.redeemed'
  | 'ai_trade.executed'
  | 'forex_investment.created'
  | 'forex_investment.redeemed'
  | 'staking.reward_claimed'
  | 'contract.event'
  | 'nft.transferred';

CreateWebhookInput

interface CreateWebhookInput {
  /** HTTPS endpoint URL. */
  url: string;
  /** Events to subscribe to. */
  events: WebhookEventType[];
  /** Optional description. */
  description?: string;
  /** Whether the webhook starts active. Default true. */
  active?: boolean;
}

UpdateWebhookInput

interface UpdateWebhookInput {
  /** Update the endpoint URL. */
  url?: string;
  /** Replace the event subscriptions. */
  events?: WebhookEventType[];
  /** Update the description. */
  description?: string;
  /** Enable or disable the webhook. */
  active?: boolean;
}

WebhookDelivery

interface WebhookDelivery {
  id: string;
  webhookId: string;
  /** Event that triggered the delivery. */
  event: WebhookEventType;
  /** HTTP status code returned by the endpoint. */
  statusCode: number;
  /** Whether the delivery was successful (2xx response). */
  success: boolean;
  /** Request payload sent to the endpoint. */
  requestBody: Record<string, unknown>;
  /** Response body returned by the endpoint (truncated). */
  responseBody?: string;
  /** Response time in milliseconds. */
  durationMs: number;
  /** Delivery attempt number (retries increment this). */
  attempt: number;
  createdAt: string;
}

DeliveryListOptions

interface DeliveryListOptions {
  /** Filter by success/failure. */
  success?: boolean;
  /** Filter by event type. */
  event?: WebhookEventType;
  limit?: number;
  cursor?: string;
}

Webhook Payload Format

Every webhook delivery sends a POST request with a JSON body:

interface WebhookPayload {
  /** Unique delivery ID. */
  id: string;
  /** Event type. */
  event: WebhookEventType;
  /** ISO 8601 timestamp. */
  timestamp: string;
  /** Project ID. */
  projectId: string;
  /** Event-specific data. */
  data: Record<string, unknown>;
}

Signature Verification

Payloads are signed with HMAC-SHA256 using the webhook's secret. The signature is sent in the X-Webhook-Signature header.

import crypto from 'crypto';

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

Examples

Create a Webhook

const res = await engine.createWebhook({
  url: 'https://myapp.com/webhooks/one',
  events: [
    'transaction.confirmed',
    'swap.completed',
    'ai_order.completed',
  ],
  description: 'Production webhook for order notifications',
});

if (res.success && res.data) {
  console.log('Webhook created:', res.data.id);
  console.log('Secret:', res.data.secret);
  // Store the secret securely for payload verification
}

List Webhooks

const res = await engine.listWebhooks();

if (res.success && res.data) {
  for (const wh of res.data) {
    console.log(`${wh.id} | ${wh.url} | Active: ${wh.active} | Events: ${wh.events.length}`);
  }
}

Update a Webhook

const res = await engine.updateWebhook('wh_abc123', {
  events: [
    'transaction.confirmed',
    'transaction.failed',
    'swap.completed',
    'swap.failed',
    'ai_order.completed',
    'ai_order.redeemed',
  ],
  active: true,
});

Test a Webhook

const res = await engine.testWebhook('wh_abc123');

if (res.success && res.data) {
  console.log(`Test delivery: ${res.data.success ? 'OK' : 'FAILED'}`);
  console.log(`Status: ${res.data.statusCode} | ${res.data.durationMs}ms`);
}

View Delivery History

const res = await engine.getWebhookDeliveries('wh_abc123', {
  success: false,
  limit: 20,
});

if (res.success && res.data) {
  for (const d of res.data) {
    console.log(`${d.createdAt} | ${d.event} | ${d.statusCode} | Attempt: ${d.attempt}`);
  }
}

Delete a Webhook

const res = await engine.deleteWebhook('wh_abc123');

if (res.success && res.data?.deleted) {
  console.log('Webhook deleted');
}

Retry Policy

Failed deliveries are retried with exponential back-off:

Attempt	Delay
1	Immediate
2	1 minute
3	5 minutes
4	30 minutes
5	2 hours

After 10 consecutive failures, the webhook is automatically disabled. Re-enable it by calling updateWebhook with active: true.

Next Steps

• Admin API -- manage users and projects.
• Contracts & NFTs API -- subscribe to contract events via webhooks.