Webhooks

黑帕云提供 Webhook 能力,可以将数据变化事件推送到第三方系统。通过 Webhook 和 API,你可以充分将黑帕云应用与企业既有的 IT 系统连接,打通业务数据,提升效率。

使用 Webhook 连接第三方系统

适用场景

目前支持业务表数据新增、更新、删除的事件推送,你可以实现:

  • 当业务表新增了数据,推送到企业微信群、钉钉、飞书群机器人
  • 用黑帕云管理销售订单,同步数据到企业 ERP 和财务系统,如新建流水、凭证等
  • 与短信/邮件平台集成,给业务表中的联系人发送短信/邮件
  • 与企业自研系统对接,将繁重的数据可视化管理交给黑帕云
  • ...

如何使用

配置 Webhook

Webhook 仅限应用管理员使用,在应用设置中选择「数据推送」,点击「添加 Webhook」。

添加 Webhook

各配置项说明:

  • 业务表:必填,数据变化事件的业务表
  • 事件:必填,响应哪些事件(数据新增、更新、删除)
  • URL:必填,第三方系统提供的接口地址,用于接收数据事件
  • Headers:HTTP 请求的 Header 信息,可用于身份校验等

填写以上信息并保存。当指定业务表的新增、更新、删除数据时,黑帕云会将事件详情以 JSON 格式,通过 HTTP POST 方式推送到指定的 URL。

数据格式

每次推送内容,包含事件基本信息和数据详情,结构如下:

字段名 数据类型 描述
id String 当前推送事件的唯一标识
eventType String 事件类型:record_updated/record_created/record_deleted
app.id String 应用 ID
app.name String 应用名称
table.id String 业务表 ID
table.name String 业务表名称
record JSON 触发事件的数据详情,详细格式参见 API 文档

JSON 样例

{
    "id": "9a517b52-3850-4a6d-9aed-ca76c813f93b",
    "eventType": "record_created",
    "app": {
        "id": "6035ad5328fc914d3399eb7f",
        "name": "客户管理"
    },
    "table": {
        "id": "6035ad5328fc914d3399eb80",
        "name": "销售线索"
    },
    "record": {
        "id": "603bacbc5fe66d624fa76702",
        "values": {
          "日期": "2019-09-01T00:00:00Z",
          "客户": "盟新传媒有限公司",
          "来源": "微信",
          "销售负责人": "贾飞舟",
          "客户姓名": "谢岩",
          "电话": "18988888881",
          "Email": "email@company.com",
          "当前阶段": "新线索",
          "创建人": {
            "id": "60332c56eef8ebb5d797603f",
            "name": "孙建平",
            "avatarUrl": "https://assets-acc.hipacloud.com/prod%2Favatars%2F60332cfceef8ebb5d795604a",
            "role": "admin"
          },
          "创建时间": "2021-02-28T14:46:20Z"
        },
        "createdAt": "2021-02-28T14:46:20Z",
        "updatedAt": "2021-02-28T14:46:20Z"
    }
}

推送测试

Webhook 配置创建完成后,你需要确保接收数据的程序已部署运行。

尝试在业务表添加一条数据,检查下服务器是否如期响应。 Webhook 列表会展示每一个配置的运行状态。如果推送失败,你可以查看到原因和发生时间。

Webhook 配置列表

注意事项

1. 推送重试机制

  • 在我们尝试向填写的地址发送 POST 请求时,我们要求用户的服务器于 5 秒内返回 2XX(如200)作为应答。
  • 对于每一次事件,如未收到正常响应,我们会尝试重新推消息,如果连续均失败,Webhook 配置创建者将会收到通知。
  • 如果连续 5 次事件未推送成功,Webhook 配置将被暂停,你需要检查服务器接口,并手动保存并启用。

Webhook 暂停推送

2. 推送出现延时

  • 批量操作可能会同时产生大量推送事件,导致实际推出的时间延后
  • 用户的服务器未正常响应,会递增时间间隔尝试重新连接

3. 新增数据后,接收到了不完整的数据,字段为空值

当你在表格视图底部添加行数据时,可能遇到该问题。事实上,你需要理解的是,在表格行被添加的那一刻,数据已经创建,即便大多数字段都还未设置。在「添加数据」对话框中新增数据,可以避免该问题。

4. 删除应用、删除业务表、删除字段不会推送事件

5. 部分第三方系统的调用接口,可能设置了 IP 白名单,也会导致推送不能完成

最后更新时间: 08月05日 11:07