Svix - 网络钩子即服务

网站 | 文档 | 社区Slack

Svix是企业级的网络钩子服务

Svix让开发者轻松发送网络钩子。开发者只需进行一次API调用，Svix就会处理可交付性、重试、安全性等问题。欲了解更多信息，请访问Svix主页。

文档

你可以在https://docs.svix.com找到通用使用文档。有关我们所有官方客户端库中每个端点的完整API文档和代码示例，请访问我们的API文档网站https://api.svix.com。

支持与社区

GitHub问题 - 报告问题并提出建议。
社区论坛 - 提问并开始讨论！
Slack - 来和我们聊天吧！

要及时了解新功能和改进，请务必关注我们的代码库！

关注并为我们的代码库加星

客户端库概述

⚡️ 功能明细 ⚡️
语言	官方支持	API支持	Webhook验证	其他说明
Go	✅	✅	✅
Python	✅	✅	✅
Typescript/Javascript	✅	✅	✅
Java	✅	✅	✅	计划支持异步。（如果您使用Kotlin，请查看我们的Kotlin库以获得协程支持。）
Kotlin	✅	✅	✅
Ruby	✅	✅	✅
C# (dotnet)	✅	✅	✅
Rust	✅	✅	✅
PHP	✅	🔜	✅

运行服务器

有多种方法可以启动Svix服务器。Docker可能是最常见的方式，但你可以选择最适合你的方法。

Svix服务器是用Rust🦀编写的，这意味着你可以将其编译成适用于各种目标平台的静态库。更多信息请参考下面的从源代码构建部分。

关于可用设置的更多信息，请参考下面的服务器配置部分。

部署

Docker

你可以从Docker Hub使用官方Svix Docker镜像。你可以使用latest标签，或者选择一个版本化的标签。

你可以使用示例docker-compose.yml文件与docker compose（最简单）、docker swarm（高级）一起使用，或者单独运行容器。

使用Docker Compose

这种方法最简单，因为它还会启动和配置redis和postgresql。

这假设你已安装Docker Compose v2。

cd server
docker compose up

独立容器

运行独立容器稍微复杂一些，因为它需要你设置一些环境变量，并让它们指向你的redis和postgres实例。你可以使用-e标志将单个环境变量传递给docker，或者创建一个类似development.env的文件，并像下面的例子那样使用--env-file标志：

docker run \
  --name svix-server \
  -p 8071:8071 \
  --env-file development.env \
  svix/svix-server

预编译二进制文件

发布版本的预编译二进制文件可在发布部分获得。

从源代码构建

Svix服务器是用Rust🦀编写的，需要Rust构建环境。

如果你已经有一个，只需运行cargo build，否则，请参考Svix服务器README获取更多关于从源代码构建服务器的信息。

运行时依赖

服务器需要以下运行时依赖才能正常工作：

PostgreSQL服务器 - 用于存储事件。
可选的Redis服务器版本6.2.0或更高 - 用于任务队列和缓存。

Redis/Valkey注意事项

持久性

请注意，建议在Redis中启用持久性，以便在Redis服务器重启和升级时保留任务。

驱逐策略

请确保你的Redis实例配置为不驱逐没有显式设置expire策略的键。这意味着maxmemory-policy应设置为noeviction或任何可用的volatile-策略。更多信息请参见Redis/Valkey文档。

服务器配置

有三种方法可以配置svix-server：环境变量、.env文件和配置文件。

配置文件

你可以在 svix-server 的当前工作目录中放置一个名为 config.toml 的文件，它会自动被识别。你可以查看示例文件以获取更多信息和完整的支持设置列表：config.toml。

以下是最重要配置的简单示例：

# 用于身份验证的JWT密钥 - 应该保密并安全生成
jwt_secret = "8KjzRXrKkd9YFcNyqLSIY8JwiaCeRc6WK4UkMnSW"

# 数据库的DSN。目前仅支持postgres。
db_dsn = "postgresql://postgres:postgres@pgbouncer/postgres"

# redis的DSN（如果不使用redis可以留空）
redis_dsn = "redis://redis:6379"

# 使用何种消息队列。
queue_type = "redis"

环境（变量或`.env`）

另外，你也可以通过设置与每个支持设置相对应的环境变量来配置 svix-server。环境变量可以直接传递，也可以通过在 .env 文件中设置。

环境变量的名称与配置名称相同，但全部大写，并以 SVIX_ 为前缀。

例如，上面的示例配置如果通过环境变量传递，会是这样的：

# 用于身份验证的JWT密钥 - 应该保密并安全生成
SVIX_JWT_SECRET = "8KjzRXrKkd9YFcNyqLSIY8JwiaCeRc6WK4UkMnSW"

# 数据库的DSN。目前仅支持postgres。
SVIX_DB_DSN = "postgresql://postgres:postgres@pgbouncer/postgres"

# redis的DSN（如果不使用redis可以留空）
SVIX_REDIS_DSN = "redis://redis:6379"

# 使用何种消息队列。
SVIX_QUEUE_TYPE = "redis"

OpenTelemetry

你可以将追踪信息发送到OpenTelemetry Collector，它允许将追踪事件转发到多个外部应用/服务，如DataDog、Jaeger、NewRelic、Prometheus、Sentry、Signoz和Zipkin。

你可以在这些说明中了解更多。

连接池大小

有两个配置变量 db_pool_max_size 和 redis_pool_max_size，分别控制PostgreSQL和Redis连接池的最大允许大小。

它们默认的最大大小为20，但如果你的数据库能够处理，更高的值可以显著提高性能。

SSRF攻击和内部IP地址

为防止SSRF攻击，默认情况下会阻止向内部IP地址发送消息。但我们理解这并不能满足每个用户的需求，例如，服务只能在内部访问。要绕过这些限制，请参阅 whitelist_subnets 配置选项，它接受一个CIDR表示法的子网数组，允许向其发送消息。

Webhook签名方案（对称vs非对称）

为确保消息的安全性和完整性，Svix在发送前会对所有webhook消息进行签名。 Svix支持两种类型的签名方案：对称（预共享密钥）和非对称（公钥）。

对称签名速度明显更快（签名速度快约50倍，验证速度快约160倍），而且更简单（这使得你的客户更容易进行验证），但它需要使用每个端点的预共享密钥（端点密钥）才能工作。另一方面，非对称签名只需要与你的客户共享公钥（非密钥）。

因此，使用对称密钥既是推荐的，也是Svix的默认设置。使用它们的方法在文档的验证签名部分中有所说明。

然而，在某些情况下使用非对称签名可能更有利，这就是为什么它们也被支持。更多信息请参阅下面的非对称签名部分。

身份验证

使用正确密钥生成的有效JWT作为Bearer。

例如：

Authorization: Bearer <JWT_TOKEN_HERE>

可以使用以下命令生成一个

svix-server jwt generate

或者如果你自己生成，请确保使用 org_23rb8YdGqMT0qIzpgGwdXfHirMu 作为 sub 字段，并使用 H256 作为算法。

对于密钥 x 的有效JWT示例（以便你可以看到结构）：

// JWT: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE2NTUxNDA2MzksImV4cCI6MTk3MDUwMDYzOSwibmJmIjoxNjU1MTQwNjM5LCJpc3MiOiJzdml4LXNlcnZlciIsInN1YiI6Im9yZ18yM3JiOFlkR3FNVDBxSXpwZ0d3ZFhmSGlyTXUifQ.USMuIPrqsZTSj3kyWupCzJO9eyQioBzh5alGlvRbrbA
// 结构（解码后）：
{
  "iat": 1655140639,
  "exp": 1970500639,
  "nbf": 1655140639,
  "iss": "svix-server",
  "sub": "org_23rb8YdGqMT0qIzpgGwdXfHirMu"
}

使用不同的签名算法

如上所述，签署JWT的默认算法是 HS256。你可以通过将 jwt_algorithm 配置设置为以下支持的值之一来选择不同的算法：HS384、HS512、RS256、RS384、RS512 或 EdDSA。

操作性（入站）webhooks

操作性webhooks是你可以订阅的webhooks，用于获取svix-server上发生的重要事件的通知。支持的事件列表可在API参考的webhooks部分中找到。

操作性webhooks利用Svix，并由一个特殊的账户服务账户控制，其ID为：org_00000000000SvixManagement00。

第一步是通过将 operational_webhook_address 配置设置为指向你的Svix服务器来启用它。这个设置最常见的值是 http://127.0.0.1:8071，但根据你的具体设置可能会有所不同。上述步骤在此实例上启用了操作性 webhook，下一步是为您的特定组织启用它。如前所述，操作性 webhook 在后台使用普通的 Svix 账户，所以我们首先需要获取此账户的身份验证令牌。为此，您应该运行：

svix-server jwt generate org_00000000000SvixManagement00

这将为您提供一个特殊的 JWT 来访问操作性 webhook 账户，该 JWT 与您在与 Svix 交互时使用的普通 JWT 不同。假设它返回的 JWT 是 op_webhook_token_123。

要为特定账户启用操作性 webhook，我们需要首先在服务账户中为其创建一个应用程序（请记住：操作性 webhook 只是在后台使用 Svix）。我们将使用默认的 Svix 账户作为示例：org_23rb8YdGqMT0qIzpgGwdXfHirMu。

curl -X 'POST' \
  'http://localhost:8071/api/v1/app/' \
  -H 'Authorization: Bearer op_webhook_token_123' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
        "name": "Operational webhook for default org",
        "uid": "org_23rb8YdGqMT0qIzpgGwdXfHirMu"
    }'

就是这样，我们现在已经为默认账户启用了操作性 webhook。剩下的唯一一件事就是添加一个接收操作性 webhook 的端点。例如：

curl -X 'POST' \
  'https://api.eu.svix.com/api/v1/app/org_23rb8YdGqMT0qIzpgGwdXfHirMu/endpoint/' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
        "url": "https://operational-webhook-destination.com/webhook/",
        "filterTypes": [
          "endpoint.updated",
          "endpoint.deleted"
        ],
    }'

注意，在创建端点时，我们使用默认账户的组织 ID 作为 app_id（或者在这种情况下是 uid）。

就是这样。您现在应该有了可工作的操作性 webhook。如果您想创建新的端点或修改现有端点，只需为服务账户生成一个 JWT，然后像使用任何其他 Svix 账户一样使用该 JWT。

非对称签名

如上所述，建议使用对称签名。但是，如果您确定需要非对称签名，请阅读以下关于设置非对称签名的说明。

配置密钥

默认情况下，Svix 服务器为端点生成对称密钥，这意味着消息将使用对称密钥进行签名。要更改此默认设置，请将 default_signature_type 配置设置为 ed25519，如下所示：

default_signature_type = "ed25519"

此外，无论默认设置如何，您仍然可以通过在端点上显式设置密钥来覆盖它。要设置对称密钥，请将端点密钥设置为以 whsec_ 为前缀的密钥，例如 whsec_51TKyHBy5KFY1Ab98GQ8V60BkWnejkWy。要设置非对称密钥，请将端点密钥设置为以 whsk_ 为前缀的有效 ed25519 base64 编码私钥，例如：whsk_6Xb/dCcHpPea21PS1N9VY/NZW723CEc77N4rJCubMbfVKIDij2HKpMKkioLlX0dRqSKJp4AJ6p9lMicMFs6Kvg==。

请注意，预期的私钥结构是：whsk_${base64(private_key + public_key)}。

出于测试目的，可以使用以下命令生成新的非对称密钥对：

$ svix-server asymmetric-key generate

Secret key: whsk_6Xb/dCcHpPea21PS1N9VY/NZW723CEc77N4rJCubMbfVKIDij2HKpMKkioLlX0dRqSKJp4AJ6p9lMicMFs6Kvg==
Public key: whpk_1SiA4o9hyqTCpIqC5V9HUakiiaeACeqfZTInDBbOir4=

签名方案

Svix 使用 ed25519(m) 对 webhook 消息进行签名，并以与对称签名相同的方式构造 m。

在验证消息时，您还应确保时间戳足够近，以限制重放攻击的可能性，如对称验证文档中所述。

关闭服务器

为了支持服务器的优雅关闭，在收到 SIGINT/SIGTERM 信号时，所有正在运行的任务都会在关闭前完成。这通常需要不到十秒钟的时间。

与 Svix 托管服务的差异

开源 Svix 调度器的主要目标之一是易用性。然而，由于我们的规模和所需的基础设施，托管的 Svix 服务相当复杂。这种复杂性对绝大多数人来说并不有用，而且会使这个项目更难使用，功能也更加有限。这就是为什么在发布之前对这段代码进行了调整，托管调度器支持的一些功能、优化和行为尚未在此存储库中提供。尽管如此，除了一些已知的不兼容性外，内部 Svix 测试套件已经通过。这意味着它们已经基本兼容，我们正在努力实现完全的功能对等。