@nimbusnexus/webhooks-sdk

@nimbusnexus/webhooks-sdk (TypeScript)

Official TypeScript SDK for NimbusNexus Webhooks — publish events, 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 { WebhookdClient, WebhookdApiError } from "@nimbusnexus/webhooks-sdk";

const wh = new WebhookdClient({ 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.deliveriesCreated);
} catch (e) {
  if (e instanceof WebhookdApiError) console.error(e.statusCode, e.code, e.message);
}

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

Develop

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