---
title: 配置应用 Webhook
description: 通过 HTTPS 端点接收带签名的应用安全事件。
editUrl: true
head: []
template: doc
sidebar:
  order: 7
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

应用 Webhook 会把受支持的安全事件通知给你的后端。它适合及时触发后续处理，但不能代替 JWKS、introspection 或其他 Sudomimus API；需要判断当前状态时，仍应调用对应的权威接口。

目前支持的第一个事件是 `APPLICATION_SIGNING_KEY_ACTIVATED`。

## 创建端点

在 [`with.sudomimus.com`](https://with.sudomimus.com) 打开应用，然后进入 **Webhooks**：

1. 填写名称和一个公网 HTTPS 端点。
2. 创建 Webhook，并立即复制签名密钥。
3. 把签名密钥保存到后端的密钥管理服务中。
4. 在事件能够触发生产操作前，先完成签名校验和重复投递处理。

每个应用最多可以配置五个端点。Viewer 可以查看端点和投递历史；Admin 与 Owner 可以创建、修改、停用、删除端点，也可以轮换签名密钥。

签名密钥只会在创建端点或轮换时显示。如果丢失，请轮换密钥，并同步更新后端。

## 校验每个请求

Sudomimus 会发送以下 header：

- `Sudomimus-Webhook-Id`
- `Sudomimus-Webhook-Timestamp`
- `Sudomimus-Webhook-Signature`

签名值以 `v1=` 开头，后面是以下内容经过 HMAC-SHA256 计算后的 Base64URL 结果：

```text
<timestamp>.<未经修改的原始请求体>
```

请先校验签名，再解析 JSON。签名比较应使用常量时间算法；请求时间与服务器时间相差超过五分钟时应拒绝；同时保存 webhook ID，避免重复投递触发同一操作。

## 正确响应并处理重试

接收事件后返回任意 `2xx` 状态。遇到超时、网络失败、`408`、`429` 或 `5xx` 时，Sudomimus 会重试；其他 `4xx` 会结束该事件的投递。

Webhook 采用至少一次投递，同一个 webhook ID 可能出现多次。事件处理必须可以安全重复执行。

Webhooks 页面会显示最近的投递状态、尝试次数、HTTP 状态和经过整理的失败原因，不会保存或展示你的响应正文。

## 端点要求

端点必须使用公网 HTTPS 和标准 TLS 端口。系统会拒绝重定向、URL 中的凭据、URL 片段、内网地址、回环地址和云元数据地址。

计划维护期间，如果不希望继续投递，请先停用端点。修改 URL 或轮换签名密钥后，尚未投递的旧事件也不会继续使用过期配置发送。

## 相关阅读

- [应用生命周期](/zh-cn/with-portal/application-lifecycle/) —— 上线或停用应用。
- [管理令牌签名密钥](/zh-cn/with-portal/organizations-and-applications/#管理令牌签名密钥) —— 当前 Webhook 事件所对应的功能。