@xlambda-tech/core

Shared HTTP client and webhook verification used by every xlambda service SDK (@xlambda-tech/media, @xlambda-tech/postgres, @xlambda-tech/redis, @xlambda-tech/email). Most people should install one of those instead of this package directly — this exists so the four don't each reimplement auth, retries, and webhook signature verification.

You'll use this package directly if you want to build a generic webhook receiver that handles multiple event families in one place, or a framework adapter this package doesn't ship yet.

Verifying and parsing webhooks

Every webhook delivery from xlambda (media processing events, livestream events, email events) is signed the same way: HMAC-SHA256 of the raw request body, keyed with your project's webhookSecret, sent as x-signature: sha256=<hex>.

import { parseWebhookEvent, XlambdaError } from '@xlambda-tech/core';

const event = parseWebhookEvent(rawBody, signatureHeader, secret);
// event is a discriminated union - narrow on event.event
if (event.event === 'email.received') {
  console.log(event.data.subject, event.data.from);
}

parseWebhookEvent throws InvalidSignatureError if the signature doesn't match. Never trust an unverified body — anyone can POST to a public URL.

Building a handler

import { createWebhookHandler } from '@xlambda-tech/core';

const handler = createWebhookHandler({
  secret: process.env.XLAMBDA_WEBHOOK_SECRET!,
  onEvent: async (event) => {
    // your logic
  },
});

export const { POST } = handler.toNextRouteHandler(); // Next.js App Router

toNodeHandler() and toNextRouteHandler() need no extra dependency (just Node builtins and the standard Fetch API). For Express or Fastify, import the dedicated adapter — keeping them out of the main entry means installing @xlambda-tech/core never pulls in either framework's types:

import { toExpressHandler } from '@xlambda-tech/core/webhooks/adapters/express';
import { toFastifyPlugin } from '@xlambda-tech/core/webhooks/adapters/fastify';

See each adapter file's own doc comment for the raw-body caveat (a JSON body-parser must not touch the request before signature verification).

XlambdaClient

import { XlambdaClient } from '@xlambda-tech/core';

const client = new XlambdaClient({ apiKey: process.env.XLAMBDA_API_KEY! });

Retries automatically on 429 (honoring X-RateLimit-Reset) and 5xx, never on 4xx. Every non-2xx response that exhausts retries throws XlambdaError with .code/.status/.details matching the platform's documented error envelope. Service packages build on top of this — you won't normally construct one yourself.