n8n 配置飞书 Webhook 签名及 Crypto 节点用法

示例命令说明：

• 请求方式：POST
• 请求头：Content-Type: application/json
• 请求体：{"msg_type":"text","content":{"text":"request example"}}
• webhook 地址：https://open.feishu.cn/open-apis/bot/v2/hook/**** 为示例值，你在实际调用时需要替换为自定义机器人真实的 webhook 地址。

执行命令后，进入自定义机器人所在群组查看测试消息。

如果请求成功，命令行将会回显以下信息：

{"StatusCode":0,"StatusMessage":"success","code":0,"data":{},"msg":"success"}

如果请求体格式错误，则会返回以下信息：

{"code":9499,"msg":"Bad Request","data":{}}

后续步骤

成功添加自定义机器人后，推荐你为自定义机器人添加安全设置，以保证机器人接收请求的安全性。

为自定义机器人添加安全设置

目前提供的安全设置方式如下：

我们强烈建议为自定义机器人添加安全设置，以提高安全性。在同一个自定义机器人中，你可以设置一个或多个方法。

• 自定义关键词：只有包含至少一个关键词的消息，可以成功发送。
• IP 白名单：只有在白名单内的 IP 地址，可以成功请求 webhook 发送消息。
• 签名校验：设置签名。发送的请求必须通过签名校验，才可以成功请求 webhook 发送消息。

方式一：设置自定义关键词

1. 在群组名称右侧点击机器人图标，打开机器人列表，找到自定义机器人并点击进入配置页面。
2. 在 安全设置 区域，选择 自定义关键词。
3. 在输入框添加关键词。最多可以同时设置 10 个关键词，多个关键词之间使用回车键间隔。
4. 点击 保存，使生效配置。

注意：自定义关键词只对 text、title 这类文本参数值生效。

方式二：设置 IP 白名单

1. 在群组名称右侧点击机器人图标，打开机器人列表，找到自定义机器人并点击进入配置页面。
2. 在 安全设置 区域，选择 IP 白名单。
3. 在输入框添加 IP 地址。支持添加 IP 地址或地址段，最多可设置 10 个。
4. 点击 保存，使配置生效。

方式三：设置签名校验

1. 在群组名称右侧点击机器人图标，打开机器人列表，找到自定义机器人并点击进入配置页面。
2. 在 安全设置 区域，选择 签名校验。
3. 点击 复制，复制秘钥。
4. 点击 保存，使配置生效。

计算签名字符串

设置签名校验后，向 webhook 发送请求需要签名校验来保障来源可信。所校验的签名需要通过时间戳与秘钥进行算法加密，即将 timestamp + "\n" + 密钥 当做签名字符串，使用 HmacSHA256 算法计算空字符串的签名结果，再进行 Base64 编码。

本文提供了以下不同语言的代码示例，用于计算获得签名字符串。

Java 示例代码

package sign;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import org.apache.commons.codec.binary.Base64;

public class SignDemo {
    public static void main(String[] args) throws NoSuchAlgorithmException, InvalidKeyException {
        String secret = "demo";
        int timestamp = 1599360473;
        System.out.printf("sign: %s", GenSign(secret, timestamp));
    }

    private static String GenSign(String secret, int timestamp) throws NoSuchAlgorithmException, InvalidKeyException {
        // 把 timestamp+"\n"+密钥当做签名字符串
        String stringToSign = timestamp + "\n" + secret;
        // 使用 HmacSHA256 算法计算签名
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(stringToSign.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
        byte[] signData = mac.doFinal(new byte[]{});
        return new String(Base64.encodeBase64(signData));
    }
}

Go 示例代码

func GenSign(secret string, timestamp int64)(string,error){
	// timestamp + key 做 sha256, 再进行 base64 encode
	stringToSign := fmt.Sprintf("%v", timestamp)+"\n"+ secret
	var data []byte
	h := hmac.New(sha256.New,[]byte(stringToSign))
	_, err := h.Write(data)
	if err !=nil{return"", err }
	signature := base64.StdEncoding.EncodeToString(h.Sum(nil))
	return signature,nil
}

Python 示例代码

import hashlib
import base64
import hmac

def gen_sign(timestamp, secret):
    # 拼接 timestamp 和 secret
    string_to_sign = '{}\n{}'.format(timestamp, secret)
    hmac_code = hmac.new(string_to_sign.encode("utf-8"), digestmod=hashlib.sha256).digest()
    # 对结果进行 base64 处理
    sign = base64.b64encode(hmac_code).decode('utf-8')
    return sign

获取签名字符串

获取签名字符串后，在向 webhook 发送请求时，需要加上时间戳（timestamp）和签名字符串（sign）字段信息。

{
  "timestamp": "1599360473",
  "sign": "xxxxxxxxxxxxxxxxxxxxx",
  "msg_type": "text",
  "content": {"text": "request example"}
}

注意：在 n8n 中用 crypto 模块获取签名字符串

HMAC 的正确用法是：

hmac.new(key=secret, msg=data, digestmod=hashlib.sha256)

但是飞书提供的代码是：

string_to_sign = '{}\n{}'.format(timestamp, secret)
hmac_code = hmac.new(string_to_sign.encode("utf-8"), digestmod=hashlib.sha256).digest()

第一个参数 key 变成了 timestamp 和 secret 的拼接（用换行符），第二个参数 msg 为空。

所以我们节点配置如下：

{"timestamp": "{{Math.round(new Date().getTime()/1000)}}",}

{{ $json.timestamp + '\n' + 'XRkoNa93xgcXy5ZwB77PLh'}}

完整工作流 json 代码如下：

{
  "nodes": [
    {
      "parameters": {
        "method": "POST",
        "url": "https://open.feishu.cn/open-apis/bot/v2/hook/************************",
        "sendBody": true,
        "specifyBody": "json",
        "jsonBody": "={\n \"timestamp\": \"{{ $json.timestamp}}\",\n \"sign\": \"{{ $json.sign}}\",\n \"msg_type\": \"text\",\n \"content\": {\n \"text\": \"request example\"\n }\n}",
        "options": {}
      },
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.2,
      "position": [496, 0],
      "id": "0cf5fa50-e7ef-405d-b1c9-5edc1dc49889",
      "name": "HTTP Request"
    },
    {
      "parameters": {},
      "type": "n8n-nodes-base.manualTrigger",
      "typeVersion": 1,
      "position": [-176, 0],
      "id": "2fc6c5ad-97ae-41ab-b932-6fdfb8481b8e",
      "name": "When clicking 'Execute workflow'"
    },
    {
      "parameters": {
        "action": "hmac",
        "type": "SHA256",
        "value": "=",
        "dataPropertyName": "sign",
        "secret": "={{ $json.timestamp + '\\n' + 'XRkoNa93xgcX**************'}}",
        "encoding": "base64"
      },
      "type": "n8n-nodes-base.crypto",
      "typeVersion": 1,
      "position": [272, 0],
      "id": "5d2be349-404f-4b4d-9acf-b6674c293774",
      "name": "Crypto"
    },
    {
      "parameters": {
        "mode": "raw",
        "jsonOutput": "={\n \"timestamp\": \"{{Math.round(new Date().getTime()/1000)}}\",\n}\n",
        "options": {}
      },
      "type": "n8n-nodes-base.set",
      "typeVersion": 3.4,
      "position": [48, 0],
      "id": "5206a964-60f9-4fa2-9e84-874b6086f467",
      "name": "Edit Fields"
    }
  ],
  "connections": {
    "When clicking 'Execute workflow'": {
      "main": [[{"node": "Edit Fields", "type": "main", "index": 0}]]
    },
    "Crypto": {
      "main": [[{"node": "HTTP Request", "type": "main", "index": 0}]]
    },
    "Edit Fields": {
      "main": [[{"node": "Crypto", "type": "main", "index": 0}]]
    }
  },
  "pinData": {},
  "meta": {
    "instanceId": "7dad39b1efdec274b0305a8cf49ffedcd26ca40b0ec7aafcaf3eb4e9d058f099"
  }
}

删除自定义机器人

在飞书群组的 设置 中，打开 群机器人 列表，找到需要删除的自定义机器人，在卡片右侧点击删除图标。

支持发送的消息类型说明

向自定义机器人 webhook 地址发送 POST 请求时，支持推送的消息格式有 文本、富文本、图片消息 以及 群名片 等。

发送文本消息

请求消息体示例

{"msg_type":"text","content":{"text":"新更新提醒"}}

参数说明

• 参数 msg_type 值为对应消息类型的映射关系，文本消息的 msg_type 对应值为 text。
• 参数 content 包含消息内容，文本消息的消息内容参数说明如下表所示。

文本消息的 @ 用法

// @ 单个用户 <at user_id="ou_xxx">名字</at>
// @ 所有人 <at user_id="all">所有人</at>

• @ 单个用户时，user_id 字段需填入用户的 Open ID 或 User ID。
• @ 所有人时，必须满足所在群开启 @ 所有人功能。

文本消息 @ 用法示例

{"msg_type":"text","content":{"text":"<at user_id=\"ou_xxx\">Tom</at> 新更新提醒"}}

发送富文本消息

请求消息体示例

{"msg_type":"post","content":{"post":{"zh_cn":{"title":"项目更新通知","content":[[{"tag":"text","text":"项目有更新:"},{"tag":"a","text":"请查看","href":"http://www.example.com/"},{"tag":"at","user_id":"ou_18eac8********17ad4f02e8bbbb"}]]}}}}

参数说明

• 参数 msg_type 值为 post。
• 参数 content 包含消息内容，由 zh_cn、en_us 语言配置组成。

发送群名片

请求消息体示例

{"msg_type":"share_chat","content":{"share_chat_id":"oc_f5b1a7eb27ae2****339ff"}}

发送图片

请求消息体示例

{"msg_type":"image","content":{"image_key":"img_ecffc3b9-8f14-400f-a014-05eca1a4310g"}}

发送飞书卡片

飞书卡片是一种轻量的消息推送应用。发送卡片时，需要将消息体的 content 字符串替换为 card 结构体，并对整个请求消息体进行 JSON 转义。

请求消息体示例

{"msg_type":"interactive","card":{"schema":"2.0","config":{"update_multi":true},"body":{"direction":"vertical","elements":[{"tag":"markdown","content":"西湖，位于中国浙江省杭州市西湖区龙井路 1 号..."}]},"header":{"title":{"tag":"plain_text","content":"今日旅游推荐"}}}}

常见问题

如何实现 @ 指定人、@ 所有人？

你可以在机器人发送的普通文本消息（text）、富文本消息（post）、消息卡片（interactive）中，使用 at 标签实现 @ 人效果。

如何获得 @ 指定人时所需要的 open_id？

自定义机器人本身不能调用接口获取用户的 open_id。你可以开发一个机器人应用，使用受管控的方案获得用户的 open_id。

方案一：通过邮箱或手机号反查用户的 open_id

方案二：解析用户发送给机器人的带 @ 人内容的消息，获取目标用户的 open_id

自定义机器人能响应用户消息吗？

不能，自定义机器人只能用于在群聊中自动发送通知，不能响应用户 @ 机器人的消息。

如何撤回自定义机器人发送的消息？

自定义机器人自身无法撤回自己发送的消息，必须由群聊内的群主或管理员进行撤回。