hookfreight

Official TypeScript SDK for Hookfreight — the webhook management platform.

Capture, inspect, replay, and reliably deliver webhooks with full visibility.

Installation

npm install hookfreight

yarn add hookfreight

pnpm add hookfreight

Requirements: Node.js 18+

Quick Start

Hookfreight Cloud

import Hookfreight from "hookfreight";

const hf = new Hookfreight({ apiKey: "hf_sk_..." });

// List recent deliveries
const { deliveries } = await hf.deliveries.list({ limit: 10 });

Self-Hosted

import Hookfreight from "hookfreight";

const hf = new Hookfreight({
  baseUrl: "http://localhost:3030/api/v1",
});

Configuration

Option	Type	Default	Description
apiKey	string	—	API key for Hookfreight Cloud. Optional for self-hosted.
baseUrl	string	https://api.hookfreight.com/v1	Base URL of the API. Override for self-hosted instances.
timeout	number	30000	Request timeout in milliseconds.

Usage

Apps

Apps group your webhook endpoints together.

// List all apps
const { apps, has_next } = await hf.apps.list({ limit: 10, offset: 0 });

// Create an app
const app = await hf.apps.create({
  name: "My App",
  description: "Handles Stripe webhooks",
});

// Get an app
const app = await hf.apps.get("app_...");

// Update an app
const updated = await hf.apps.update("app_...", { name: "Renamed App" });

// Delete an app (also deletes connected endpoints)
const { app: deleted, connected_endpoints } = await hf.apps.delete("app_...");

Endpoints

Endpoints receive webhooks and forward them to your services.

// List endpoints for an app
const { endpoints } = await hf.endpoints.list("app_...");

// Create an endpoint
const endpoint = await hf.endpoints.create({
  name: "Stripe Webhooks",
  app_id: "app_...",
  forward_url: "https://example.com/webhooks/stripe",
  authentication: {
    header_name: "Authorization",
    header_value: "Bearer my-secret",
  },
});

// Your webhook URL is:
// https://api.hookfreight.com/<endpoint.hook_token>

// Get an endpoint
const ep = await hf.endpoints.get("end_...");

// Update an endpoint
await hf.endpoints.update("end_...", {
  is_active: false, // pause during maintenance
});

// Delete an endpoint
await hf.endpoints.delete("end_...");

Events

Events are captured webhook requests.

// List events with filters
const { events } = await hf.events.list({
  endpoint_id: "end_...",
  method: "POST",
  start_date: "2026-01-01T00:00:00Z",
  end_date: "2026-02-01T00:00:00Z",
  limit: 50,
});

// Get a single event (includes full headers, body, etc.)
const event = await hf.events.get("evt_...");
console.log(event.body); // Original webhook payload

// List events for a specific endpoint
const { events: epEvents } = await hf.events.listByEndpoint("end_...");

// Replay an event (triggers a new delivery)
await hf.events.replay("evt_...");

Deliveries

Deliveries track forwarding attempts for each event.

// List deliveries with filters
const { deliveries } = await hf.deliveries.list({
  status: "failed",
  start_date: "2026-02-01T00:00:00Z",
  limit: 100,
});

// List deliveries for a specific event
const { deliveries: eventDeliveries } = await hf.deliveries.listByEvent("evt_...");

// Retry a failed delivery
await hf.deliveries.retry("dlv_...");

// Get queue statistics
const stats = await hf.deliveries.queueStats();
console.log(stats);
// { waiting: 0, active: 2, completed: 150, failed: 3, delayed: 0 }

Error Handling

The SDK throws typed errors for different failure modes:

import Hookfreight, {
  NotFoundError,
  ValidationError,
  AuthenticationError,
  ConnectionError,
} from "hookfreight";

try {
  await hf.apps.get("app_nonexistent");
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log("App not found");
  } else if (error instanceof ValidationError) {
    console.log("Validation errors:", error.errors);
  } else if (error instanceof AuthenticationError) {
    console.log("Invalid API key");
  } else if (error instanceof ConnectionError) {
    console.log("Network error:", error.message);
  }
}

Error Class	HTTP Status	When
ValidationError	400	Invalid request parameters
AuthenticationError	401	Missing or invalid API key
PermissionError	403	Insufficient permissions
NotFoundError	404	Resource doesn't exist
APIError	Other	Any other API error
ConnectionError	—	Network failures, timeouts

All errors extend HookfreightError, so you can catch all SDK errors with a single type:

import { HookfreightError } from "hookfreight";

try {
  await hf.apps.list();
} catch (error) {
  if (error instanceof HookfreightError) {
    // Any SDK error
  }
}

CommonJS

The SDK supports both ESM and CommonJS:

const { Hookfreight } = require("hookfreight");

const hf = new Hookfreight({ apiKey: "hf_sk_..." });

Examples

See the examples/ directory for runnable scripts:

• basic-usage.ts — Create apps, endpoints, list events
• retry-failed-deliveries.ts — Find and retry failed deliveries
• manage-endpoints.ts — Pause/resume endpoints in CI/CD
• monitor-queue.ts — Queue health monitoring for alerting

Run any example with:

HOOKFREIGHT_API_KEY=hf_sk_... npx tsx examples/basic-usage.ts

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

git clone https://github.com/Hookfreight/hookfreight-ts.git
cd hookfreight-ts
npm install
npm run build
npm run typecheck

License

Apache-2.0