将回调发送至开发者服务器
你可以自建一个服务器，通过 Webhook 模式接收飞书开放平台的回调订阅通知，该模式需要你提供服务器的公网访问地址，在回调触发时飞书开放平台会向该公网访问地址发送 HTTP POST 请求，请求内包含回调数据。
步骤一（可选）：配置加密策略
你可以根据企业数据安全要求，配置加密策略，以加密传输回调数据并校验请求来源是否有风险。加密策略内包含 Encrypt Key、Verification Token 两个参数，Encrypt Key 用于加密传输回调请求，Verification Token 用于校验请求是否来自飞书开放平台。
Encrypt Key
该参数用于实现回调订阅请求的加密传输。
- 如果配置 Encrypt Key，飞书开放平台向请求地址推送回调数据时会进行加密，加密推送能够提高数据安全性，建议你配置该参数。
- 如果未配置 Encrypt Key，飞书开放平台向请求地址推送回调数据时不会加密处理，直接明文推送。
加密推送的回调示例如下，你的本地服务器接收到加密回调体后，需要进行解密处理。解密步骤参考接收回调。
{
"encrypt": "FIAfJPGRmFZWkaxPQ1XrJZVbv2JwdjfLk4jx0k/U1deAqYK3AXOZ5zcHt/cC4ZNTqYwWUW/EoL+b2hW/C4zoAQQ5CeMtbxX2zHjm+E4nX/Aww+FHUL6iuIMaeL2KLxqdtbHRC50vgC2YI7xohnb3KuCNBMUzLiPeNIpVdnYaeteCmSaESb+AZpJB9PExzTpRDzCRv+T6o5vlzaE8UgIneC1sYu85BnPBEMTSuj1ZZzfdQi7ZW992Z4dmJxn9e8FL2VArNm99f5Io3c2O4AcNsQENNKtfAAxVjCqc3mg5jF0123123flX1UOF5fzJ0sApG2OEn9wfyPDRBsApn9o+fceF9hNrYBGsdtZrZYyGG387CGOtKsuj8e2E8SNp+Pn4E9oYejOTR+ZNLNi+twxaXVlJhr6l+RXYwEiMGQE9zGFBD6h2dOhKh3W84p1GEYnSRIz1+9/Hp66arjC7RCrhuW5OjCj4QFEQJiwgL123123VsL03CxxFZarzxzffryrWUG3VkRdHRHbTsC34+ScoL5MTDU1QAWdqUC1T7xT0lCvQELaIhBTXAYrznJl6PlA83oqlMxpHh0gZBB1jFbfoUr7OQbBs1xqzpYK6Yjux6diwpQB1zlZErYJUfCqK7G/zI9yK/60b4HW0123+123123="
}适用场景
- 应用校验收到的回调推送是来自飞书开放平台，而非伪造。
- 应用防止被重放攻击。重放攻击是指飞书开放平台推送给应用的回调被第三方截获，然后再把回调原封不动的多次发送给应用。这样可能会对应用造成数据安全隐患，也可能会影响应用服务器的性能。
配置 Encrypt Key 后，你本地的服务器可以基于 Encrypt Key 进行签名校验，以保证应用接收到的都是飞书开放平台推送的合法回调。有关签名校验的详细介绍，请参考接收回调。
加密原理
回调请求的内容采用 AES-256-CBC 加密。加密原理如下：
- 使用 SHA256 对
Encrypt Key进行哈希，得到密钥key。 - 使用 PKCS7Padding 方式将回调内容进行填充。
- 生成 16 字节的随机数作为初始向量
iv。 - 使用
iv和key对回调内容加密，得到encrypted_event。 - 应用收到的密文为
base64(iv+encrypted_event)。
Verification Token
Verification Token 是应用的验证标识。开发者后台会为应用自动生成 Verification Token，当飞书开放平台推送回调数据时，会携带 Verification Token 值，你可以据此 Token 验证推送的回调是否属于当前应用。
操作步骤
登录开发者后台。
在应用列表中点击具体应用，进入应用管理详情页面。
在左侧导航栏，选择 开发配置 > 事件与回调。
进入 加密策略 页签，配置 Encrypt Key 或者 Verification Token。
点击 重置 图标，可重置参数值。
点击 编辑 图标，可编辑参数值。
步骤二：设置订阅方式
登录 开发者后台。
进入指定应用，并在应用详情页的左侧导航栏，选择 开发配置 > 事件与回调。
在 事件与回调 页面，点击 回调配置 页签。
在 订阅方式 右侧，点击编辑按钮。
选择 将回调发送至开发者服务器，配置 请求地址 并点击 保存。
:::note 每个应用内只能配置一个回调请求地址，且需要保证该地址为 IPv4 公网地址，后续该应用订阅的所有回调，均会在触发时向请求地址发送回调数据。 :::
填写地址并保存时，飞书服务器会向该请求地址发送一个用于校验地址有效性的 HTTP POST 请求，请求格式为 JSON、带
challenge参数。在请求地址所属的开发者服务器内，需要接收该 HTTP POST 请求，并在 1 秒内返回包含challenge参数的响应体，成功完成校验后才可以保存。如何处理并响应 HTTP POST 请求，参见下文 响应 POST 校验请求 章节。
响应 POST 校验请求
根据飞书应用是否配置了 Encrypt Key，响应 POST 校验请求的方式分为以下两种。
方式一：应用未配置 Encrypt Key
飞书服务器发送的校验请求体如下所示。
{
"challenge": "1b6aef1a-401f-406a-be41-f48911eabcef", // 需要在响应中原样返回的值。
"token": "xxxxxx", // 即应用的 Verification Token，通过该值你可以判断请求是否来自飞书开放平台的指定应用。
"type": "url_verification" // 固定值，表示这是一个验证请求。
}参数说明如下表所示。
| 参数 | 类型 | 描述 |
|---|---|---|
| challenge | String | 用于验证的字段，需在响应体中原样返回该值。 示例值：1b6aef1a-401f-406a-be41-f48911eabcef |
| token | String | 应用验证标识 Verification Token。你可以通过该 Token 验证请求是否属于当前应用。 在 开发者后台 > 应用详情页 > 开发配置 > 事件与回调 > 安全设置 模块，可查看应用的 Verification Token。 |
| type | String | 回调类型。用于校验的回调类型固定取值为 url_verification，表示当前请求是在验证 URL 合法性。 |
当请求地址收到该 POST 校验请求时，需要提取出 challenge 值，并在 1 秒内返回包含 challenge 值的响应数据。响应体示例如下：
{
"challenge": "1b6aef1a-401f-406a-be41-f48911eabcef"
}方式二：应用配置了 Encrypt Key
如果应用配置了 Encrypt Key，则会推送加密后的请求。请求体如下所示。
{
"encrypt": "ds3da3sj32421lkkld4xxxx" // 加密字符串。
}你需要在接收请求的服务器内解密 encrypt 字符串，并在 1 秒内返回提取出的 challenge 值。解密方式可参见接收回调。
解密后的数据结构如下所示。
json{ "challenge": "1b6aef1a-401f-406a-be41-f48911eabcef", // 需要在响应中原样返回的值。 "token": "xxxxxx", // 即应用的 Verification Token，通过该值你可以判断请求是否来自飞书开放平台的指定应用。 "type": "url_verification" // 固定值，表示这是一个验证请求。 }响应体示例如下所示。
json{ "challenge": "1b6aef1a-401f-406a-be41-f48911eabcef" }
示例代码
飞书开放平台针对常见的编程语言，提供了 将回调发送至开发者服务器 订阅方式的示例代码。你可以点击下方链接，查看对应语言的示例代码。
| 编程语言 | 示例代码 |
|---|---|
| Java | 集成 Servlet 容器，将回调发送至开发者服务器 |
| Python | 将回调发送至开发者服务器 |
| Golang | 将回调发送至开发者服务器 |
| Node.js | 将回调发送至开发者服务器 |