用途
Svix Quickstart 用于帮助开发者以最快速度让项目通过 Svix 发出第一条 Webhook 消息。它适合以下场景：首次将 Svix 添加到项目、用户需要发送第一条 Webhook 并需要设置步骤、基于 Svix API 对 Webhook 流程进行原型验证。
该技能明确说明不适合用于设计非平凡的集成，例如多租户路由、接收第三方 Webhook、嵌入门户等，这些场景需要先进行架构评估，再编写快速入门代码。
主要能力
该技能提供一套按步骤推进的工作流：
- 从仪表盘获取 API Key（由用户完成，无法脚本化）。
- 检测项目语言并安装匹配的 SDK。
- 按客户创建 Application，使用自己的客户 ID 作为 uid。
- 发送带有事件类型和负载的 Message。
- 通过 App Portal（推荐）或 API 为客户订阅端点。
- 验证消息已发出。
技能强调从项目推断 SDK，而不是假设语言；示例使用 JavaScript/TypeScript，但各 SDK 的调用形态一致。编写代码前应始终对照实时文档确认所检测语言的确切语法。文档 URL 后追加 .md 可获得适合 LLM 阅读的版本。
使用方式
第 1 步：获取 API Key
用户必须自行创建，无法通过脚本完成。让用户打开 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 });
按 uid 创建 Application 是幂等的——使用相同 uid 再次调用会返回现有 Application，而不是报错。
第 4 步：发送 Message
一条 Message 是面向一个 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。
适用场景
- 首次为项目添加 Svix。
- 用户希望发送第一条 Webhook 并需要设置步骤。
- 基于 Svix API 对 Webhook 流程进行原型验证。
限制
- 不适用于设计非平凡的集成（多租户路由、接收第三方 Webhook、嵌入门户），这些需要先进行架构评估。
- API Key 必须由用户手动创建，无法脚本化。
- 应始终对照实时文档确认所检测语言的确切语法，不要假设。
后续步骤
- 完整的分语言参考 → https://docs.svix.com/quickstart.md
- 验证签名、Channels、App Portal 嵌入、幂等性、Ingest → https://docs.svix.com/overview.md
检查清单
- API Key 已生成并设置为 SVIX_AUTH_TOKEN（未硬编码）。
- 已为项目语言安装 SDK。
- 已使用客户 uid 创建 Application。
- 已发送带有 eventType 和 payload 的第一条消息。
- 至少订阅了一个端点（App Portal 链接或 endpoint.create）。
- 消息和投递尝试在仪表盘 / App Portal 中可见。