RaytonX
EN联系我们
返回博客
飞书多维表格Webhook

飞书多维表格集成实践：Webhook 同步、消息监听与 API 读写

结合实际项目，介绍如何将飞书多维表格接入业务系统，包括通过自动化触发 Webhook、在无法暴露公网时使用群消息监听，以及通过 SDK 调用多维表格 API 完成数据读写。

RaytonX
3 min read

飞书多维表格集成实践

在业务系统与飞书协同时，多维表格常常承担轻量数据录入、流程承接和团队协作的角色。
如果希望把这些数据进一步同步到内部系统，常见需求通常包括三类：

  • 用户新增记录后，自动同步到业务系统
  • 表格发生变更后，尽快通知系统侧处理
  • 系统主动回写多维表格，更新字段或状态

本文结合实际项目经验，整理一套更适合工程落地的接入方案。

一、优先方案：通过自动化触发 Webhook

如果你的系统可以提供公网可访问的接口，最直接的做法是使用飞书多维表格的「自动化」能力，在新增记录时调用系统的 Webhook。

相比定时轮询 API，这种方式更适合低频但要求及时同步的场景，原因也很直接：

  • 不需要持续轮询，资源消耗更低
  • 触发链路更清晰，便于排查问题
  • 数据同步更接近实时，用户感知更好

基本流程

  1. 系统侧提供一个 Webhook 接口，用于接收飞书回调
  2. 在多维表格中配置自动化规则
  3. 当用户新增记录时，飞书自动调用该 Webhook
  4. 系统接收记录信息后，完成入库或后续业务处理

这类方案适合大多数“新增一条记录，系统侧立即处理”的需求，例如线索录入、工单创建、项目登记等。

二、无法暴露公网时的替代方案

并不是所有系统都适合直接开放公网 Webhook。
如果系统部署在内网、测试环境或受限网络中，可以考虑一套折中但很实用的方案：

通过多维表格自动化将变更信息发送到飞书群聊，再由系统使用长连接监听群消息，感知数据变更。

这套方式的核心思路是：

  • 多维表格负责“发出通知”
  • 飞书群聊作为“消息中转层”
  • 系统侧通过 WebSocket 长连接接收事件

这样做的好处是，无需对外暴露回调地址，依然可以获得较及时的变更通知。

三、整体接入思路

在实践中，我们更推荐下面这条链路：

  1. 创建飞书自建应用
  2. 给应用配置机器人能力与消息读取权限
  3. 在事件与回调中启用长连接订阅
  4. 在多维表格自动化中，将变更通知发送到指定群聊
  5. 系统侧监听群消息，并在收到通知后调用多维表格 API 读取或更新数据

需要注意的是，多维表格相关事件在部分场景下并不总是适合作为唯一触发源。
因此在实际项目中，使用“自动化 + 群消息通知 + 系统侧 API 读写”的组合方式，通常会更稳定、更容易控制。

四、飞书应用配置要点

1. 创建自建应用

在飞书开放平台创建应用后，建议至少完成以下配置：

  • 开启 机器人 能力
  • 在权限管理中添加消息读取权限
  • 在事件与回调中启用 长连接 订阅方式

如果你的系统还需要主动读写多维表格数据，还需要补充多维表格相关权限。

2. 推荐关注的权限

用于监听群消息时，通常需要：

  • im:message
  • im:message.group_msg

用于读写多维表格时，通常需要：

  • bitable:app

权限名称和粒度可能会随飞书平台调整，正式上线前建议再对照开放平台控制台确认一次。

3. 记录应用凭证

你需要保存好以下信息，供服务端初始化 SDK 使用：

  • App ID
  • App Secret

随后由服务端换取 tenant_access_token，再调用飞书开放接口。

五、多维表格自动化配置建议

在多维表格中配置自动化时，可以将“新增记录”或“记录更新”作为触发条件，并将动作设置为“发送飞书消息到群聊”。

这里有一个非常容易踩坑的细节：

尽量让消息由用户侧触发发送，而不是由机器人自身发送。

原因在于，飞书的消息事件机制会避免机器人消息形成循环触发。
如果通知消息完全由机器人产生，系统侧未必能够按预期收到对应的事件回调。

因此，更稳妥的做法是：

  • 由多维表格自动化发送消息到指定群聊
  • 系统监听该群中的消息事件
  • 收到事件后再调用业务逻辑或多维表格 API

六、使用长连接接收事件

飞书支持通过长连接方式与开放平台建立 WebSocket 通道。
当订阅事件发生时，平台会通过该连接主动将事件推送到你的服务。

这类方式特别适合以下场景：

  • 服务不方便暴露公网地址
  • 希望减少额外的回调配置成本
  • 需要在本地或内网环境快速验证流程

下面是一段简化后的示例代码：

import * as Lark from "@larksuiteoapi/node-sdk";

const baseConfig = {
  appId: "xxx",
  appSecret: "xxx",
};

const wsClient = new Lark.WSClient({
  ...baseConfig,
  loggerLevel: Lark.LoggerLevel.debug,
});

wsClient.start({
  eventDispatcher: new Lark.EventDispatcher({}).register({
    "im.message.receive_v1": async (data) => {
      console.log(data);
      // 在这里解析群消息内容
      // 再根据消息中的记录信息，调用系统逻辑或多维表格 API
    },
  }),
});

如果只是为了感知“某条记录新增或变更了”，这类消息监听方式通常已经足够。

七、通过 SDK 读写多维表格

当系统收到通知后，下一步往往就是调用飞书 API 读取记录详情，或把处理结果回写到多维表格。

常见参数

调用更新记录接口时，通常会用到以下参数：

  • app_token：多维表格的应用级标识
  • table_id：数据表 ID
  • record_id：记录 ID
  • fields：需要更新的字段内容

其中：

  • app_token 通常可从多维表格链接或对象信息中获取
  • record_id 往往可以在自动化回调或后续查询中获得

更新记录示例

下面是一段简单的封装示例，用于说明基本调用方式：

import axios from "axios";
import keys from "../../configBridge";

interface FeishuConfig {
  app_id: string;
  app_secret: string;
}

interface TokenInfo {
  token: string;
  expiresAt: number;
}

export class Feishu {
  private config: FeishuConfig;
  private tenantTokenInfo: TokenInfo | null = null;

  constructor() {
    this.config = {
      app_id: keys.feishu.FEISHU_APP_ID || "",
      app_secret: keys.feishu.FEISHU_APP_SECRET || "",
    };
  }

  private isTokenExpired(tokenInfo: TokenInfo | null): boolean {
    if (!tokenInfo) return true;
    return Date.now() >= tokenInfo.expiresAt;
  }

  async getTenantAccessToken() {
    if (!this.isTokenExpired(this.tenantTokenInfo)) {
      return this.tenantTokenInfo!.token;
    }

    const response = await axios.post(
      "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal",
      {
        app_id: this.config.app_id,
        app_secret: this.config.app_secret,
      }
    );

    const data = response.data;
    if (data.code !== 0 || !data.tenant_access_token) {
      throw new Error(`获取 tenant_access_token 失败: ${data.msg}`);
    }

    const expiresIn = data.expire;
    this.tenantTokenInfo = {
      token: data.tenant_access_token,
      expiresAt: Date.now() + expiresIn * 1000 - 60_000,
    };

    return this.tenantTokenInfo.token;
  }

  async updateRecord(params: {
    appToken: string;
    tableId: string;
    recordId: string;
    fields: Record<string, any>;
  }) {
    const token = await this.getTenantAccessToken();

    const url = `https://open.feishu.cn/open-apis/bitable/v1/apps/${params.appToken}/tables/${params.tableId}/records/${params.recordId}`;

    const response = await axios.put(
      url,
      { fields: params.fields },
      {
        headers: {
          Authorization: `Bearer ${token}`,
        },
      }
    );

    if (response.data.code !== 0) {
      throw new Error(`更新记录失败: ${response.data.msg}`);
    }

    return response.data;
  }
}

八、实践建议

如果你的目标只是把新增记录同步到系统，优先使用：

  • 自动化 + Webhook

如果你的系统暂时无法提供公网入口，可以考虑：

  • 自动化 + 群消息通知 + 长连接监听

如果你的系统还需要进一步回写数据、更新状态或补充字段，再结合：

  • 飞书 SDK / API 读写多维表格

这种拆分方式的好处在于，通知链路和数据操作链路彼此独立，后续无论是排查问题还是扩展流程，都会更清晰。

总结

飞书多维表格并不只是一个协作工具，它也可以成为业务系统与团队工作流之间的轻量连接层。

在真实项目中，选择哪种接入方式，关键不在于“是否能调通 API”，而在于：

  • 系统是否能暴露公网接口
  • 是否需要接近实时的通知能力
  • 是否需要系统主动回写表格数据

如果能根据部署环境和业务流程合理组合 Webhook、长连接事件与 API 读写，多维表格就可以比较顺畅地融入现有系统架构中。