Svix Quickstart 的目标是让项目尽可能快地通过 Svix 发出第一条 Webhook。
适用场景
首次将 Svix 添加到项目中；用户想发送第一条 Webhook 并需要设置步骤；针对 Svix API 进行 Webhook 流程原型设计。
不适用场景
设计非平凡的集成（多租户路由、接收第三方 Webhook、嵌入门户）——这些在任何快速入门代码之前都需要先做架构梳理。
工作流程
- 从仪表盘获取 API 密钥（由用户完成，无法脚本化）。
- 检测项目语言并安装匹配的 SDK。
- 为每个客户创建一个 Application，以自有客户 ID（uid）作为键。
- 发送带事件类型和负载的 Message。
- 让客户订阅端点——App Portal（推荐）或 API。
- 验证消息已发出。
应根据项目推断 SDK，不要假设。查看仓库并使用该语言的 SDK。文档中的示例为 JavaScript/TypeScript；各 SDK 的调用形态一致。编写代码前，务必对照实时文档确认所检测语言的确切语法。https://docs.svix.com/quickstart.md#create-a-consumer-application 每个语言都有对应标签页（在任何文档 URL 后追加 .md 可获得 LLM 可读版本）。
第 1 步：获取 API 密钥
必须由用户创建，无法脚本化。让用户打开 API Access 页面生成令牌，然后将其存储为环境变量。切勿硬编码。
export SVIX_AUTH_TOKEN="testsk_..."
令牌与区域相关（美国、欧盟、印度）。SDK 会从令牌读取区域，因此无需提供 base URL。
第 2 步：安装 SDK
从 https://docs.svix.com/quickstart.md#install-the-svix-sdk-optional 获取所检测语言的当前安装命令——其中列出了每种语言（以及 CLI）的确切命令，应将其作为事实来源，而不是猜测包名或版本。
第 3 步：为每个客户创建一个 Application
每个客户对应一个 Svix Application。将自有内部客户标识符作为 uid 传入，以便之后无需存储 Svix 生成的 ID 即可寻址。
import { Svix } from "svix";
const svix = new Svix(process.env.SVIX_AUTH_TOKEN!);
const app = await svix.application.create({ name: "Acme Inc", uid: "customer-123", // your internal customer ID });
创建 Application 对 uid 是幂等的——使用相同 uid 再次调用会返回现有 Application，而不是报错。
第 4 步：发送消息
一条消息就是一个 Application 的一个 Webhook 事件。使用第 3 步的 uid 寻址 Application。同时在负载中包含事件类型，以便消费者无需解析头部即可分支处理。
从代码库推断事件类型
await svix.message.create("customer-123", { eventType: "invoice.paid", eventId: "evt_Wqb1k73rXprtTm7Qdlr38G", // optional, for idempotency payload: { type: "invoice.paid", id: "invoice_WF7WtCLFFtd8ubcTgboSFNql", status: "paid", }, });
eventType 使用 <group>.<event> 约定（例如 invoice.paid）。将 eventId 设置为从源事件派生的值可使发送幂等——Svix 会对具有相同 eventId 的重复发送去重。
第 5 步：让客户订阅 Webhook
消息只会扇出到该 Application 已存在的端点。有两种添加方式：
App Portal（推荐）。一个预构建、可品牌化的 UI，客户可在其中添加自己的端点、检查投递日志并重放失败——无需 Svix 账户。从后端生成短期魔法链接：
const dashboard = await svix.authentication.appPortalAccess("customer-123", {}); // redirect or embed dashboard.url
Endpoint API。当通过自有 UI 收集 URL 时，自行创建端点：
await svix.endpoint.create("customer-123", { url: "https://api.example.com/svix-webhooks/", description: "My main endpoint", });
验证
svix.message.create(...) 返回且未抛出异常。
在仪表盘（或 App Portal）中，消息出现在该 Application 下，并显示对每个端点的投递尝试。
若要在没有真实消费者的情况下进行端到端测试，可使用 svix listen 获取一个临时公共 URL 并转发到 localhost——参见 https://docs.svix.com/tutorials/cli.md。
后续步骤
各语言完整参考 → https://docs.svix.com/quickstart.md
验证签名、Channels、App Portal 嵌入、幂等性、Ingest → https://docs.svix.com/overview.md
检查清单
API 密钥已生成并设置为 SVIX_AUTH_TOKEN（未硬编码）https://docs.svix.com/quickstart#install-the-svix-sdk-optional
已为项目语言安装 SDK
已使用客户 uid 创建 Application
已发送带 eventType 和负载的第一条消息
至少订阅了一个端点（App Portal 链接或 endpoint.create）
消息和投递尝试在仪表盘 / App Portal 中可见