@nimbusnexus/webhooks-sdk (TypeScript)

Official TypeScript SDK for NimbusNexus Webhooks — publish events, manage your endpoints / keys / deliveries, and verify the webhooks you receive. Zero runtime dependencies (uses the built-in fetch and node:crypto); Node ≥ 20.

npm install @nimbusnexus/webhooks-sdk

Verify an incoming webhook (subscribers)

Always verify the signature before trusting a webhook — it proves the request really came from webhookd and wasn't tampered with or replayed. Pass the raw request body (do not re-serialize).

import { verify } from "@nimbusnexus/webhooks-sdk";

const ok = verify(endpointSigningSecret, rawBody, req.headers["x-webhook-signature"], {
  timestamp: req.headers["x-webhook-timestamp"],
});
if (!ok) return res.status(400).end(); // forged, tampered, or outside the 300s replay window

Publish an event (producers)

import { WebhooksClient, WebhooksApiError } from "@nimbusnexus/webhooks-sdk";

const wh = new WebhooksClient({ baseUrl: "https://webhooks.example.com", apiKey: "whsk_…" });

try {
  const event = await wh.publish(
    "order.created",
    { orderId: "ord_123", total: 4200 },
    { idempotencyKey: "order-123" }, // makes the publish safe to retry
  );
  console.log(event.eventUid, event.projectId, event.deliveriesCreated);
} catch (e) {
  if (e instanceof WebhooksApiError) console.error(e.statusCode, e.code, e.message);
}

Projects. A project is addressed by its id (prj_…), not a slug. Omit projectId — as above — to publish into your workspace's default project; the server resolves it. Pass one only to target a specific project:

await wh.publish("order.created", { orderId: "ord_123" }, { projectId: "prj_3f9a…" });

The id is opaque and per-workspace, so there is no client-side sentinel for "the default project": leaving projectId unset omits the field entirely. The response (event.projectId) always carries the id the event actually landed in.

Transient failures (network errors, 429, 5xx) are retried with backoff (a 429 honours Retry-After); other 4xx throw WebhooksApiError carrying the {error:{code,message}} envelope.

Outbox / durable buffering (producers)

publish() calls webhookd synchronously — if webhookd is unreachable it rejects and the event is lost. The write-first outbox decouples the two: enqueue() durably persists the event to a pluggable Store and resolves IMMEDIATELY (no network); drain() (or a background drainer) ships the buffered events later. Every send carries Idempotency-Key = record.id, so a re-drain after a crash or a lost response never double-publishes — webhookd dedupes. Delivery is at-least-once: nothing is lost while webhookd is down.

import { WebhooksClient, SqliteStore } from "@nimbusnexus/webhooks-sdk";

// 1. Configure a durable store (survives process restarts; needs Node >= 22.5 for node:sqlite).
const store = new SqliteStore("outbox.db");

const wh = new WebhooksClient({
  baseUrl: "https://webhooks.example.com",
  apiKey: "whsk_…",
  store,
});

// 2. enqueue() instead of publish() — writes to the store and resolves at once, NO network call.
const { id } = await wh.enqueue("order.created", { orderId: "ord_123", total: 4200 });

// 3a. Drain on demand (resolves to { sent, failed, remaining }):
await wh.drain();

// 3b. …or run a background drainer that calls drain() every 5s until you stop it.
wh.startDrainer(5);
// ... your app keeps enqueuing; the drainer ships in the background ...
wh.stopDrainer();

Idempotency guarantee. id is the idempotencyKey you pass (or a generated UUID v4) and becomes the Idempotency-Key header on every delivery attempt for that record. If the process crashes after a send but before the response is recorded, the next drain() re-sends with the same key and webhookd returns the original event without re-fanning-out. A record that keeps failing is retried with capped exponential backoff up to maxAttempts (default 10), then parked dead (never retried again, retrievable via store.listDead()) and passed to the optional onDead callback.

enqueue takes the same optional projectId as publish (omit it for the default project). It is persisted on the buffered record as a nullable project_id — null means "the workspace's default project", and drain then omits the field from the publish body.

Built-in stores — pass one as store in ClientOptions:

| Store | Durable? | Extra needed | | --- | --- | --- | | MemoryStore | No (in-process) | — (built-in) | | FileStore(dir) | Yes (per-record JSON files) | — (built-in) | | SqliteStore(path) | Yes (transactional) | — (built-in node:sqlite, Node ≥ 22.5) | | RedisStore({ url }) | Yes | npm install redis | | PostgresStore({ connectionString }) | Yes | npm install pg |

The core SDK stays zero-dependency; redis / pg are optionalDependencies, imported lazily only when you construct RedisStore / PostgresStore.

Manage endpoints, keys & deliveries (operators)

The same client wraps the control-plane API — register receivers, mint keys, and drain the dead-letter queue from code (needs an admin-scoped key). Management methods return the API's snake_case JSON through typed interfaces (Endpoint, ApiKey, Delivery, Page<T>); list methods return { items, next_offset }; deleteEndpoint / revokeApiKey resolve to void (a 204).

import { WebhooksClient } from "@nimbusnexus/webhooks-sdk";

const wh = new WebhooksClient({ baseUrl: "https://webhooks.example.com", apiKey: "whsk_admin_…" });

// --- Endpoints ---------------------------------------------------------------
// Create a receiver — its signing secret is in the response exactly once, so persist it now.
// Omit `projectId` (here and on listEndpoints) for the workspace's default project.
const ep = await wh.createEndpoint("https://your-app.example/webhooks", {
  subscriptions: [{ match_kind: "prefix", pattern: "order." }],
  description: "orders service",
});
const { id: endpointId, secret: signingSecret } = ep;

await wh.listEndpoints();                          // default project — { items, next_offset }
await wh.listEndpoints({ projectId: "prj_3f9a…" }); // a specific project, by id
await wh.getEndpoint(endpointId);

// PATCH — send only the keys you want to change (omitted = unchanged, null = cleared):
await wh.updateEndpoint(endpointId, { max_attempts: 10, status: "disabled" });

await wh.rotateEndpointSecret(endpointId);       // returns the new secret, once
await wh.enableEndpoint(endpointId);             // recover an auto-disabled endpoint
await wh.deleteEndpoint(endpointId);             // -> void (204)

// --- API keys ----------------------------------------------------------------
const key = await wh.createApiKey({ name: "ci-publisher", scope: "publish", expiresInDays: 90 });
console.log(key.key);                            // shown once
await wh.revokeApiKey(key.id);                   // -> void (204)

// --- Deliveries / dead-letter recovery ---------------------------------------
const dead = await wh.listDeliveries({ status: "dead" });
for (const d of dead.items) await wh.redeliver(d.id);

Develop

npm install
npm run typecheck && npm run lint && npm run test && npm run build