@gethook/node — SDK Reference

About 886 wordsAbout 3 min

Installation

npm install @gethook/node

Setup

import { GethookClient } from "@gethook/node";

const client = new GethookClient({
  baseUrl: process.env.GETHOOK_API_URL!,
  // Return the stored API key on every request
  getToken: () => localStorage.getItem("gethook_api_key"),
  // Redirect to login on 401
  onUnauthorized: () => { window.location.href = "/login"; },
});

Error handling

All methods throw GethookApiError on non-2xx responses.

import { GethookClient, GethookApiError } from "@gethook/node";

try {
  await client.deleteSource("<id>");
} catch (err) {
  if (err instanceof GethookApiError) {
    console.error(`HTTP ${err.status}:`, err.body);
  }
}

Health

`healthz()`

Liveness check.

Returns: Promise<object>

const result = await client.healthz();

`readyz()`

Readiness check.

Returns: Promise<object>

const result = await client.readyz();

Accounts

`createAccount(body: CreateAccountRequest)`

Create account.

Creates a new account and returns a bootstrap API key. No authentication required.

Parameters:

body CreateAccountRequest — Request body (see type)

Returns: Promise<AccountBootstrapData>

const body: CreateAccountRequest = {
  name: "My Company",
};
const result = await client.createAccount(body);

Auth

Authenticates with email/password and returns a fresh API key on success.

Parameters:

body LoginRequest — Request body (see type)

Returns: Promise<AccountBootstrapData>

const body: LoginRequest = {
  email: "admin@example.com",
  password: "supersecret",
};
const result = await client.login(body);

`register(body: RegisterRequest)`

Creates a new account with email/password credentials and returns a bootstrap API key.

Parameters:

body RegisterRequest — Request body (see type)

Returns: Promise<AccountBootstrapData>

const body: RegisterRequest = {
  email: "admin@example.com",
  name: "My Company",
  password: "supersecret",
};
const result = await client.register(body);

API Keys

`listApiKeys()`

List API keys.

Returns: Promise<APIKey[]>

const result = await client.listApiKeys();

`createApiKey(body: CreateAPIKeyRequest)`

Create API key.

Creates a new API key for the authenticated account. The full key is only returned once.

Parameters:

body CreateAPIKeyRequest — Request body (see type)

Returns: Promise<APIKeyWithSecret>

const body: CreateAPIKeyRequest = {
  name: "production",
};
const result = await client.createApiKey(body);

`deleteApiKey(id: string)`

Revoke API key.

Parameters:

id string — API key UUID

Returns: Promise<void>

await client.deleteApiKey("<id>");

Sources

`listSources()`

List sources.

Returns: Promise<Source[]>

const result = await client.listSources();

`createSource(body: CreateSourceRequest)`

Create source.

Creates a new webhook source endpoint. Returns an ingest_url to share with the event sender.

Parameters:

body CreateSourceRequest — Request body (see type)

Returns: Promise<Source>

const body: CreateSourceRequest = {
  name: "Stripe webhooks",
};
const result = await client.createSource(body);

`getSource(id: string)`

Get source.

Parameters:

id string — Source UUID

Returns: Promise<Source>

const result = await client.getSource("<id>");

Destinations

`listDestinations()`

List destinations.

Returns: Promise<Destination[]>

const result = await client.listDestinations();

`createDestination(body: CreateDestinationRequest)`

Create destination.

Creates a new webhook delivery destination. The signing_secret is encrypted at rest and never returned.

Parameters:

body CreateDestinationRequest — Request body (see type)

Returns: Promise<Destination>

const body: CreateDestinationRequest = {
  name: "My endpoint",
  url: "https://example.com/webhooks",
};
const result = await client.createDestination(body);

`getDestination(id: string)`

Get destination.

Parameters:

id string — Destination UUID

Returns: Promise<Destination>

const result = await client.getDestination("<id>");

`updateDestination(id: string, body: UpdateDestinationRequest)`

Update destination.

Parameters:

id string — Destination UUID
body UpdateDestinationRequest — Request body (see type)

Returns: Promise<Destination>

const body: UpdateDestinationRequest = {
  active: true,
  auth_config: {},
  custom_headers: {},
};
const result = await client.updateDestination("<id>", body);

Routes

`listRoutes()`

List routes.

Returns: Promise<Route[]>

const result = await client.listRoutes();

`createRoute(body: CreateRouteRequest)`

Create route.

Creates a routing rule that forwards matching events from a source to a destination.

Parameters:

body CreateRouteRequest — Request body (see type)

Returns: Promise<Route>

const body: CreateRouteRequest = {
  destination_id: "uuid",
};
const result = await client.createRoute(body);

Stats

`getStats()`

Get dashboard stats.

Returns: Promise<StatsData>

const result = await client.getStats();

Ingest

`ingest()`

Ingest webhook event.

Accepts an inbound webhook. The path token authenticates the source — no Bearer header required.

Returns: Promise<void>

await client.ingest();

Events (Inbound)

`listEvents(params?: { limit?: integer; offset?: integer })`

List inbound events.

Parameters:

params.limit integer — Max results (default 25, max 200) (optional)
params.offset integer — Pagination offset (optional)

Returns: Promise<EventListData>

const result = await client.listEvents({ limit: ..., offset: ... });

`getEvent(id: string)`

Get inbound event.

Parameters:

id string — Event UUID

Returns: Promise<EventDetailData>

const result = await client.getEvent("<id>");

`replayEvent(id: string)`

Replay inbound event.

Creates a new queued copy of the event for re-delivery.

Parameters:

id string — Event UUID

Returns: Promise<void>

await client.replayEvent("<id>");

Events (Outbound)

`listOutboundEvents(params?: { limit?: integer; offset?: integer })`

List outbound events.

Parameters:

params.limit integer — Max results (default 25, max 200) (optional)
params.offset integer — Pagination offset (optional)

Returns: Promise<EventListData>

const result = await client.listOutboundEvents({ limit: ..., offset: ... });

`publishOutboundEvent(body: PublishOutboundEventRequest)`

Publish outbound event.

Queues a new outbound event for delivery to all matching route destinations.

Parameters:

body PublishOutboundEventRequest — Request body (see type)

Returns: Promise<PublishOutboundData>

const body: PublishOutboundEventRequest = {
  payload: "{"order_id":"123"}",
};
const result = await client.publishOutboundEvent(body);

`getOutboundEvent(id: string)`

Get outbound event.

Parameters:

id string — Event UUID

Returns: Promise<EventDetailData>

const result = await client.getOutboundEvent("<id>");

`replayOutboundEvent(id: string)`

Replay outbound event.

Parameters:

id string — Event UUID

Returns: Promise<void>

await client.replayOutboundEvent("<id>");

Brand & White-Labeling

`getBrandSettings()`

Get brand settings.

Returns: Promise<BrandSettings>

const result = await client.getBrandSettings();

`upsertBrandSettings(body: UpsertBrandSettingsRequest)`

Upsert brand settings.

Creates or replaces white-label brand settings for the account.

Parameters:

body UpsertBrandSettingsRequest — Request body (see type)

Returns: Promise<BrandSettings>

const body: UpsertBrandSettingsRequest = {
  company_name: "Acme Corp",
  docs_title: "Acme Webhooks",
  logo_url: "https://example.com/logo.png",
};
const result = await client.upsertBrandSettings(body);

Custom Domains

`listCustomDomains()`

List custom domains.

Returns: Promise<CustomDomain[]>

const result = await client.listCustomDomains();

`createCustomDomain(body: CreateCustomDomainRequest)`

Create custom domain.

Parameters:

body CreateCustomDomainRequest — Request body (see type)

Returns: Promise<CustomDomain>

const body: CreateCustomDomainRequest = {
  domain: "webhooks.example.com",
};
const result = await client.createCustomDomain(body);