配置应用 Webhook
应用 Webhook 会把受支持的安全事件通知给你的后端。它适合及时触发后续处理,但不能代替 JWKS、introspection 或其他 Sudomimus API;需要判断当前状态时,仍应调用对应的权威接口。
目前支持的第一个事件是 APPLICATION_SIGNING_KEY_ACTIVATED。
在 with.sudomimus.com 打开应用,然后进入 Webhooks:
- 填写名称和一个公网 HTTPS 端点。
- 创建 Webhook,并立即复制签名密钥。
- 把签名密钥保存到后端的密钥管理服务中。
- 在事件能够触发生产操作前,先完成签名校验和重复投递处理。
每个应用最多可以配置五个端点。Viewer 可以查看端点和投递历史;Admin 与 Owner 可以创建、修改、停用、删除端点,也可以轮换签名密钥。
签名密钥只会在创建端点或轮换时显示。如果丢失,请轮换密钥,并同步更新后端。
校验每个请求
Section titled “校验每个请求”Sudomimus 会发送以下 header:
Sudomimus-Webhook-IdSudomimus-Webhook-TimestampSudomimus-Webhook-Signature
签名值以 v1= 开头,后面是以下内容经过 HMAC-SHA256 计算后的 Base64URL 结果:
<timestamp>.<未经修改的原始请求体>请先校验签名,再解析 JSON。签名比较应使用常量时间算法;请求时间与服务器时间相差超过五分钟时应拒绝;同时保存 webhook ID,避免重复投递触发同一操作。
正确响应并处理重试
Section titled “正确响应并处理重试”接收事件后返回任意 2xx 状态。遇到超时、网络失败、408、429 或 5xx 时,Sudomimus 会重试;其他 4xx 会结束该事件的投递。
Webhook 采用至少一次投递,同一个 webhook ID 可能出现多次。事件处理必须可以安全重复执行。
Webhooks 页面会显示最近的投递状态、尝试次数、HTTP 状态和经过整理的失败原因,不会保存或展示你的响应正文。
端点必须使用公网 HTTPS 和标准 TLS 端口。系统会拒绝重定向、URL 中的凭据、URL 片段、内网地址、回环地址和云元数据地址。
计划维护期间,如果不希望继续投递,请先停用端点。修改 URL 或轮换签名密钥后,尚未投递的旧事件也不会继续使用过期配置发送。