---

---

一、关于 Svix

• github : https://github.com/svix/svix-webhooks/
• 官网：https://svix.com/
• 文档 : https://docs.svix.com/
• API : https://api.svix.com
• 社区 Slack : https://svix.com/slack | 论坛：https://github.com/svix/svix-webhooks/discussions

---

Svix 让开发人员可以轻松发送 webhook。开发人员只需进行一次 API 调用，Svix 便会负责交付能力、重试、安全性等。有关更多信息，请参阅Svix 主页。

要及时了解新功能和改进，请务必关注 repo : https://github.com/svix/svix-webhooks/

---

---

Client Library Overview

⚡️ Feature Breakdown ⚡️
Language	Officially Supported	API Support	Webhook Verification	Other Notes
Go	✅	✅	✅
Python	✅	✅	✅
Typescript/Javascript	✅	✅	✅
Java	✅	✅	✅	Async support planned. (If you use kotlin, checkout our kotlin library for coroutine support.)
Kotlin	✅	✅	✅
Ruby	✅	✅	✅
C# (dotnet)	✅	✅	✅
Rust	✅	✅	✅
PHP	✅	🔜	✅

---

---

与 Svix 托管服务的区别

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

---

二、运行服务器

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

Svix 服务器是用 Rust 🦀 编写的，这意味着您可以将其编译为各种目标的静态库。有关更多信息，请参阅下面的从源代码构建部分。

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

---

1、部署

---

1.1 Docker

您可以使用Docker Hub中的官方 Svix Docker 镜像：https://hub.docker.com/r/svix/svix-server

您也可以使用 latest 标签，或者使用 the versioned tags 之一。

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

---

1) 使用 Docker Compose

这个替代方案是最简单的，因为它也将启动和redis配置postgresql。

假设您已经安装了 Docker Compose v2。

cd server
docker compose up

---

2) 独立容器

运行独立容器稍微高级一些，因为它需要您设置一些环境变量并让它们指向您的redis和postgres实例。

您可以使用标志将各个环境变量传递给 docker -e，或者只需创建一个文件（如development.env） 并像以下示例一样使用 --env-file 标志：

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

---

1.2 预编译的二进制文件

已发布版本的预编译二进制文件可在发布部分中找到。

https://github.com/svix/svix-webhooks/releases

---

1.3 从源代码构建

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

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

---

2、运行时依赖项

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

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

---

3、Redis/Valkey 注意事项

---

持久性

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

---

Eviction 政策

请确保您的 Redis 实例配置为 不逐出 未明确设置 expire 策略的密钥。这意味着maxmemory-policy应设置为noeviction或任何可用volatile-策略。有关更多信息，请参阅 Redis/Valkey 文档。

---

4、服务器配置

有三种配置方式svix-server：环境变量，.env文件和配置文件。

---

4.1 配置文件

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

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

# The JWT secret for authentication - should be secret and securely generated
jwt_secret = "8KjzRXrKkd9YFcNyqLSIY8JwiaCeRc6WK4UkMnSW"

# The DSN for the database. Only postgres is currently supported.
db_dsn = "postgresql://postgres:postgres@pgbouncer/postgres"

# The DSN for redis (can be left empty if not using redis)
redis_dsn = "redis://redis:6379"

# What kind of message queue to use.
queue_type = "redis"

---

4.2 环境（变量或.env）

或者，您可以svix-server通过为每个支持的设置设置等效的环境变量来进行配置。环境变量可以直接传递，也可以通过在文件中设置它们来传递.env。

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

例如，如果在环境中传递上述示例配置，它将如下所示：

# The JWT secret for authentication - should be secret and securely generated
SVIX_JWT_SECRET = "8KjzRXrKkd9YFcNyqLSIY8JwiaCeRc6WK4UkMnSW"

# The DSN for the database. Only postgres is currently supported.
SVIX_DB_DSN = "postgresql://postgres:postgres@pgbouncer/postgres"

# The DSN for redis (can be left empty if not using redis)
SVIX_REDIS_DSN = "redis://redis:6379"

# What kind of message queue to use.
SVIX_QUEUE_TYPE = "redis"

---

4.3 OpenTelemetry

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

您可以在这些说明中看到更多内容。

---

4.4 连接池大小

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

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

---

4.5 SSRF 攻击和内部 IP 地址

为了防止 SSRF 攻击，默认情况下会阻止向内部 IP 地址发送消息。

但是，我们知道这不能满足每个用户的需求，例如，服务只能在内部访问。要绕过这些限制，请参阅配置选项whitelist_subnets，它接受 CIDR 符号子网数组以允许向其发送消息。

---

4.6 Webhook 签名方案（对称与非对称）

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

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

鉴于上述情况，建议使用对称密钥，这也是 Svix 的默认设置。它们的使用已记录在文档的验证签名部分中。

但是，在某些情况下，使用非对称签名可能会有所帮助，这就是为什么它们也受到支持的原因。有关更多信息，请参阅下面的非对称签名部分。

---

5、验证

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

例如：

Authorization: Bearer <JWT_TOKEN_HERE>

---

使用以下方式生成一个

svix-server jwt generate

---

或者如果您正在生成自己的，请确保用作org_23rb8YdGqMT0qIzpgGwdXfHirMu字段sub并H256用作算法。

机密的有效 JWT 示例x（以便您可以看到结构）：

// JWT: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE2NTUxNDA2MzksImV4cCI6MTk3MDUwMDYzOSwibmJmIjoxNjU1MTQwNjM5LCJpc3MiOiJzdml4LXNlcnZlciIsInN1YiI6Im9yZ18yM3JiOFlkR3FNVDBxSXpwZ0d3ZFhmSGlyTXUifQ.USMuIPrqsZTSj3kyWupCzJO9eyQioBzh5alGlvRbrbA
// Structure (when decoded):
{
  "iat": 1655140639,
  "exp": 1970500639,
  "nbf": 1655140639,
  "iss": "svix-server",
  "sub": "org_23rb8YdGqMT0qIzpgGwdXfHirMu"
}

---

使用不同的签名算法

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

---

6、操作（传入）webhook

操作性 webhook 是您可以订阅的 webhook，以便收到 svix-server 上发生的重要事件的通知。支持的事件列表可在API 参考的 webhook 部分中找到。

操作 webhook 使用 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 帐户，这与您与 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。

---

7、非对称签名

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

---

配置按键

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

default_signature_type = "ed25519"

---

此外，无论默认值设置为多少，您仍然可以通过在端点上明确设置密钥来覆盖它。

要设置对称密钥，请将端点密钥设置为以 为前缀的密钥whsec_，例如whsec_51TKyHBy5KFY1Ab98GQ8V60BkWnejkWy。

要设置非对称密钥，请将端点密钥设置为以 为前缀的有效ed25519 base64 编码私钥，whsk_例如 ： 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方式与对称签名相同。

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

---

8、关闭服务器

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

---

2024-05-24（五）