HookBridge Node.js SDK

Official HookBridge SDK for Node.js and TypeScript. Send webhooks with guaranteed delivery, automatic retries, and full observability.

Installation

npm install @hookbridge/sdk

Quick Start

import { HookBridge } from '@hookbridge/sdk';

const hookbridge = new HookBridge({
  apiKey: 'hb_live_xxxxxxxxxxxxxxxxxxxx'
});

// Send a webhook
const result = await hookbridge.send({
  endpoint: 'https://customer.app/webhooks',
  payload: {
    event: 'order.created',
    orderId: 'ord_12345',
    amount: 99.99
  }
});

console.log('Message ID:', result.messageId);

Features

• Guaranteed Delivery: Webhooks are stored durably before acknowledgment
• Automatic Retries: Intelligent retry with exponential backoff
• Idempotency: Prevent duplicate webhook sends
• Full Observability: Query logs, metrics, and message status
• Type Safety: Full TypeScript support with detailed types

Usage

Send a Webhook

const result = await hookbridge.send({
  endpoint: 'https://customer.app/webhooks',
  payload: { event: 'user.created', userId: 'usr_123' },
  headers: { 'X-Tenant-Id': 'tenant_abc' },
  idempotencyKey: 'user-123-created'
});

Check Message Status

const message = await hookbridge.getMessage(result.messageId);
console.log(message.status); // 'queued', 'succeeded', 'pending_retry', 'failed_permanent'

Query Delivery Logs

const logs = await hookbridge.getLogs({
  status: 'failed_permanent',
  startTime: new Date('2025-01-01'),
  limit: 100
});

for (const msg of logs.messages) {
  console.log(msg.messageId, msg.lastError);
}

Get Metrics

const metrics = await hookbridge.getMetrics('24h');
console.log(`Success rate: ${(metrics.successRate * 100).toFixed(1)}%`);
console.log(`Average latency: ${metrics.avgLatencyMs}ms`);

Replay Failed Messages

// Replay a specific message
await hookbridge.replay(messageId);

// Or replay from the Dead Letter Queue
const dlq = await hookbridge.getDLQMessages();
for (const msg of dlq.messages) {
  await hookbridge.replayFromDLQ(msg.messageId);
}

Manage Retries

// Cancel a pending retry (moves to DLQ)
await hookbridge.cancelRetry(messageId);

// Trigger immediate retry for a pending message
await hookbridge.retryNow(messageId);

API Key Management

// List API keys
const keys = await hookbridge.listAPIKeys();

// Create a new API key
const newKey = await hookbridge.createAPIKey({
  label: 'Production backend',
  mode: 'live'
});
console.log('Save this key:', newKey.key); // Only shown once!

// Delete an API key
await hookbridge.deleteAPIKey('key_abc123');

Configuration

const hookbridge = new HookBridge({
  // Required: Your API key
  apiKey: 'hb_live_xxxxxxxxxxxxxxxxxxxx',

  // Optional: Custom base URL (default: https://api.hookbridge.io)
  baseUrl: 'https://api.hookbridge.io',

  // Optional: Request timeout in ms (default: 30000)
  timeout: 30000,

  // Optional: Number of retries for failed requests (default: 3)
  retries: 3
});

Error Handling

import {
  HookBridge,
  AuthenticationError,
  ValidationError,
  RateLimitError,
  NotFoundError,
  IdempotencyError
} from '@hookbridge/sdk';

try {
  await hookbridge.send({ ... });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof ValidationError) {
    console.error('Invalid request:', error.message);
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limited. Retry after ${error.retryAfter}s`);
  } else if (error instanceof IdempotencyError) {
    console.error('Duplicate request with different payload');
  } else {
    throw error;
  }
}

Webhook Delivery

When HookBridge delivers your webhook, it includes these headers:

• X-Webhook-Signature: HMAC-SHA256 signature for verification
• X-Webhook-Id: Message ID for tracking
• X-Webhook-Timestamp: Unix timestamp of the send request
• Any custom headers you specified

Retry Behavior

• Fast retries (for 429 responses): 30s, 60s, 120s, 240s, 300s
• Slow retries (for other errors): 30m, 2h, 6h, 12h, 24h, 48h, 72h, 96h
• Maximum 8 total attempts before moving to the Dead Letter Queue

Requirements

• Node.js 18.0.0 or later

License

MIT