步骤一：选择订阅方式（将回调发送至开发者服务器）

你可以自建一个服务器，通过 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。

点击重置图标，可重置参数值。

点击编辑图标，可编辑参数值。

步骤二：设置订阅方式

登录开发者后台。

进入指定应用，并在应用详情页的左侧导航栏，选择 开发配置 > 事件与回调。

在 事件与回调 页面，点击 回调配置 页签。

在 订阅方式 右侧，点击编辑按钮。

选择 将回调发送至开发者服务器，配置 请求地址 并点击保存。

每个应用内只能配置一个回调请求地址，且需要保证该地址为 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 值。解密方式可参见接收回调。

解密后的数据结构如下所示。

{ 
    "challenge": "1b6aef1a-401f-406a-be41-f48911eabcef",    // 需要在响应中原样返回的值。
    "token": "xxxxxx",    // 即应用的 Verification Token，通过该值你可以判断请求是否来自飞书开放平台的指定应用。
    "type": "url_verification"    // 固定值，表示这是一个验证请求。
}

响应体示例如下所示。

{ 
    "challenge": "1b6aef1a-401f-406a-be41-f48911eabcef"
}

示例代码

飞书开放平台针对常见的编程语言，提供了 将回调发送至开发者服务器 订阅方式的示例代码。你可以点击下方链接，查看对应语言的示例代码。

编程语言	示例代码
Java	集成 Servlet 容器，将回调发送至开发者服务器
Python	将回调发送至开发者服务器
Golang	将回调发送至开发者服务器
Node.js	将回调发送至开发者服务器

步骤一：选择订阅方式（将回调发送至开发者服务器）

步骤一（可选）：配置加密策略#

Encrypt Key#

适用场景#

加密原理#

Verification Token#

操作步骤#

步骤二：设置订阅方式#

响应 POST 校验请求#

方式一：应用未配置 Encrypt Key#

方式二：应用配置了 Encrypt Key#

示例代码#