Public API

Svix (client class)

class Svix {
  constructor(token: string, options?: SvixOptions);
  application: Application;
  endpoint: Endpoint;
  message: Message;
  messageAttempt: MessageAttempt;
  eventType: EventType;
  integration: Integration;
  health: Health;
  authentication: Authentication;
  // ...and more resource accessors
}

The main entry point. Instantiate once per server process with your API token. Access all Svix resources as properties. Use SvixOptions to set a custom serverUrl for EU/US regions, configure numRetries, or inject a custom fetch implementation for testing.

SvixOptions

type SvixOptions = {
  debug?: boolean;
  serverUrl?: string;
  requestTimeout?: number;
  fetch?: typeof fetch;
} & XOR<
  { retryScheduleInMs?: number[] },
  { numRetries?: number }
>;

Configuration object passed to the Svix constructor. Use serverUrl to target a specific regional endpoint (e.g. https://api.us.svix.com or https://api.eu.svix.com). Use numRetries (default: 2) or retryScheduleInMs (custom delay array) to control retry behavior. Provide a custom fetch to intercept HTTP calls in tests or edge runtimes.

Webhook (verification class)

// exported from ./webhook via `export * from "./webhook"`
class Webhook {
  constructor(secret: string);
  verify(payload: string, headers: Record<string, string>): unknown;
  sign(msgId: string, timestamp: Date, payload: string): string;
}

Used on the receiving end to verify that incoming webhook payloads were signed by Svix. Construct with the endpoint's signing secret (found in your Svix dashboard), then call verify() with the raw request body string and the request headers. Throws if the signature is invalid.

ApiException

class ApiException extends Error {
  status: number;
  body: unknown;
}

Thrown by all SDK methods when the Svix API returns a non-2xx response. Catch it to inspect the HTTP status code and response body for structured error handling.

Working examples

Scenario - Send a webhook message to an application

Create a Svix application (logical grouping for a customer) and send a typed event message to all its endpoints.

import { Svix } from "svix";
import type { ApplicationIn, MessageIn } from "svix";

const svix = new Svix(process.env.SVIX_AUTH_TOKEN!);

async function sendWebhook(customerId: string, payload: Record<string, unknown>) {
  // Ensure application exists for this customer
  const app = await svix.application.getOrCreate({
    name: `customer-${customerId}`,
    uid: customerId,
  } satisfies ApplicationIn);

  // Send a message
  const msg = await svix.message.create(app.id, {
    eventType: "invoice.paid",
    payload: {
      type: "invoice.paid",
      ...payload,
    },
  });

  console.log("Message sent:", msg.id);
}

sendWebhook("user_123", { invoiceId: "inv_abc", amount: 4900 });

Scenario - Verify an incoming webhook signature (Express)

Protect a webhook receiver endpoint by validating the Svix signature before processing events.

import express from "express";
import { Webhook, ApiException } from "svix";
import type { WebhookRequiredHeaders } from "svix";

const app = express();
app.use(express.raw({ type: "application/json" }));

const wh = new Webhook(process.env.SVIX_WEBHOOK_SECRET!);

app.post("/webhooks/svix", (req, res) => {
  const headers = {
    "svix-id": req.headers["svix-id"] as string,
    "svix-timestamp": req.headers["svix-timestamp"] as string,
    "svix-signature": req.headers["svix-signature"] as string,
  } satisfies WebhookRequiredHeaders;

  let event: unknown;
  try {
    event = wh.verify(req.body.toString(), headers);
  } catch (err) {
    return res.status(400).json({ error: "Invalid signature" });
  }

  console.log("Verified event:", event);
  res.status(200).json({ received: true });
});

app.listen(3000);

Scenario - Manage endpoints and list message attempts

Add a delivery endpoint for a customer application and inspect failed delivery attempts for debugging.

import { Svix } from "svix";
import type { EndpointIn } from "svix";

const svix = new Svix(process.env.SVIX_AUTH_TOKEN!);
const APP_ID = "app_customer_abc";

async function setupAndInspect() {
  // Create an endpoint
  const endpoint = await svix.endpoint.create(APP_ID, {
    url: "https://example.com/webhooks",
    description: "Production receiver",
    filterTypes: ["invoice.paid", "invoice.failed"],
  } satisfies EndpointIn);

  console.log("Endpoint created:", endpoint.id);

  // List recent message attempts for this endpoint
  const attempts = await svix.messageAttempt.listByEndpoint(APP_ID, endpoint.id, {
    limit: 20,
  });

  for (const attempt of attempts.data) {
    console.log(`Attempt ${attempt.id}: status=${attempt.status}, msgId=${attempt.msgId}`);
  }
}

setupAndInspect().catch(console.error);

File walkthrough

• .github/ - Contains GitHub Actions workflows for CI, release automation, and security scanning across every language SDK.
• bridge/ - The Svix Bridge daemon: forwards events between message queues and Svix, or Svix to arbitrary HTTP targets.
• codegen/ - Mustache/OpenAPI templates and scripts that generate the SDK source for all languages from the Svix API spec.
• csharp/ - Standalone C# SDK targeting .NET; mirrors the JavaScript API surface in C#.
• go/ - Standalone Go SDK with idiomatic Go patterns; independently importable via pkg.go.dev.
• java/ - Java SDK; synchronous, Maven-published.
• javascript/ - TypeScript/JavaScript SDK; the primary target for this block. Contains src/index.ts, all API resource classes, models, and the Webhook verifier.
• kotlin/ - Kotlin SDK with coroutine support.
• php/ - PHP SDK, Composer-distributed.
• python/ - Python SDK, PyPI-distributed, supports async.
• ruby/ - Ruby gem SDK.
• rust/ - Rust crate SDK published on crates.io.
• server/ - Self-hostable Svix server written in Rust; used for on-premise deployments.
• static-assets/ - Shared logos and imagery used across documentation and README files.
• svix-cli/ - A CLI tool for interacting with Svix from the terminal.
• tools/ - Internal developer scripts (codegen helpers, release utilities).
• regen_openapi.py - Python script to pull the latest OpenAPI spec and regenerate all SDK clients.

Common pitfalls and fixes

• Raw body required for webhook verification: Express's json() middleware parses the body before your handler sees it; wh.verify() needs the raw string. Fix: use express.raw({ type: "application/json" }) on the webhook route only.
• XOR constraint on SvixOptions: You cannot pass both numRetries and retryScheduleInMs; TypeScript will error at compile time. Fix: pick one retry strategy and remove the other key.
• Regional serverUrl mismatch: Tokens issued in the EU region will return 401 against the US endpoint. Fix: set serverUrl: "https://api.eu.svix.com" explicitly when using EU accounts.
• ESM/CJS interop: If your project uses "type": "module", ensure your bundler resolves the correct exports field from the svix package. Fix: set "moduleResolution": "bundler" or "node16" in tsconfig.json.
• Webhook secret format: The signing secret from the dashboard includes a whsec_ prefix; pass it verbatim to new Webhook(secret) - the SDK handles the prefix internally.
• ApiException not caught: Unhandled rejections from svix.message.create() crash the process silently in some runtimes. Fix: always wrap SDK calls in try/catch and inspect err.status for 409 (conflict) or 429 (rate limit).

Vibe-coding prompt template

I have the Svix JavaScript/TypeScript SDK source located in `source/javascript/`.
There is a complete integration guide in `USAGE.md`.
The upstream package name is `svix`.

Please help me integrate the Svix webhook SDK into my existing Node.js/TypeScript project step by step:

1. Read `USAGE.md` fully before writing any code.
2. Read `source/javascript/src/index.ts` to understand all available exports.
3. Read `source/javascript/src/models/index.ts` to understand the available request/response types.
4. Add the `svix` npm package as a dependency (or wire the local source path in tsconfig paths).
5. Create a `src/webhooks/svixClient.ts` module that:
   - Instantiates the `Svix` class using `SVIX_AUTH_TOKEN` from environment variables.
   - Exports typed helper functions for: creating/getting an application, sending a message, and listing message attempts.
6. Create a `src/webhooks/verifier.ts` module that:
   - Uses the `Webhook` class to verify incoming payloads using `SVIX_WEBHOOK_SECRET`.
   - Wraps verification in a typed Express middleware function.
7. Show me how to register the middleware on an existing Express router.
8. Show me how to catch `ApiException` and return structured error responses.

Use only exports visible in `source/javascript/src/index.ts` and `source/javascript/src/models/index.ts`.
Do not invent any API methods or types not present in those files.

License and credit

The Svix SDK is released under the MIT License. See source/LICENSE for the full license text. Upstream source and documentation: https://github.com/svix/svix-webhooks. Published npm package: https://www.npmjs.com/package/svix.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

完全なインストールガイドと統合プロンプトは購入後に解放されます。

Ory Ecosystem Multi-Language API Client SDKs

Automation, Utilities & Developer Tools

無料