帮助中心集成

为了: 管理员

查找 webhook 事件和有效载荷

十个信息流事件分别发送什么内容,消息是如何加密的,以及如何使用你的密钥解密。

在本文中4 个部分

此页面列出了通过WebhookWebhook 您提供给中心的地址,以便中心可以在信息流帖子或评论发生更改时向您的系统发送消息。发送的各种事件信息,包括每条消息的传输方式以及解密后所含内容。

活动

事件屏幕上发送时content 持有
add_post帖子已创建有人在某个案件的动态列表中发布了相关内容new:帖子的文本内容
modify_post该帖子已修改。该帖子的文本被修改了。new:新的文本
delete_post该帖子已被删除。某篇帖子已被删除。old:其文本
add_post_comment评论已创建完成有人在帖子下发表了评论。new:评论的文本
modify_post_comment评论内容已修改该评论的文本已被修改。new:新的文本
delete_post_comment该评论已被删除。一条评论被删除了。old:其文本
add_post_media媒体内容已经创建完成一篇帖子中添加了一个文件。new:指向该文件的链接
delete_post_media该帖子已被删除。某个文件已从某篇帖子中移除。old:指向被删除文件的链接
add_post_comment_media评论发布媒介已经创建完成有一个文件被添加到了评论中。new:指向该文件的链接
delete_post_comment_media该评论发布工具已被删除。某个文件已被从注释中移除。old:指向被删除文件的链接
  • 在你的中心系统中,每个案例都会将相关信息发送出去,无论变化是由员工、客户、虚拟助手虚拟助手 一个自动化的团队成员,负责发布欢迎信息、签到信息和公司动态;其发布的帖子带有虚拟助理徽章。,还是通过导入文件或API密钥引起的。即使作者已经离开了该案例,帖子的事件信息仍然会持续记录下来。
  • 删除一个案例并不会产生任何效果,甚至连delete_post这些相关帖子也会被一并删除。一旦案例被删除,API会返回404错误。
  • 只有对帖子的评论才会引发事件。笔记、任务、表单、电子签名、事件及其评论都不会引发任何效果。同样,改变帖子可见性也无法产生任何影响。
  • 发送包含文件的帖子时,会先发送一个add_post,然后为每个文件分别发送一个add_post_media。
  • 文件链接的有效期为48小时。一旦文件被删除,该链接也会立即失效,因此在使用删除功能时可能无法正常打开链接。
  • 文本中出现了“<@”来表示某个人的用户ID,同时还有“>”和“<@cu-4f1c2a9e8b7d60>”等标识。

送货

  • 每条消息都作为POST请求发送到web钩子的地址,这些请求的Body中包含了一个字段payload:即加密后的消息内容。
  • 如果在10秒内状态无法达到400以上,则视为已送达。
  • 如果某个订单的配送失败,那么该订单就不会被再次发送。如果连续出现两次这样的情况,就需要处理相关的Webhook问题了;请参阅修复无法发送Webhook的问题部分的内容。
  • 一条消息可能会重复出现,或者顺序混乱。可以使用事件、项目的ID以及when来标识这种情况。
{"payload": "eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkExMjhDQkMtSFMyNTYifQ.…"}

解密

payload是一个以紧凑形式表示的JWE,采用RSA-OAEP和A128CBC-HS256算法进行加密。该Web钩子的密钥就是对应的私钥,保存为PEM格式的文件,文件起始内容为-----BEGIN PRIVATE KEY-----。可以使用下载到的文件,或者直接复制包含所有字符的密钥文本进行使用。任何JOSE库都可以对其进行解密。

使用jwcrypto库来操作Python语言

import json
from jwcrypto import jwk, jwt

with open("webhook-private-key.pem", "rb") as f:
    key = jwk.JWK.from_pem(f.read())

def read_message(body):
    token = jwt.JWT(jwt=body["payload"], key=key, expected_type="JWE")
    return json.loads(token.claims)

Node.js,配合jose模块使用

import { readFileSync } from 'node:fs';
import { compactDecrypt, importPKCS8 } from 'jose';

const key = await importPKCS8(readFileSync('webhook-private-key.pem', 'utf8'), 'RSA-OAEP');

export async function readMessage(body) {
  const { plaintext } = await compactDecrypt(body.payload, key);
  return JSON.parse(new TextDecoder().decode(plaintext));
}

没有单独的签名。你的中心节点永远不会显示用于加密的密钥,因此,如果一条消息能够用你的秘密密钥进行解密,那么这条消息肯定来自你的中心节点;而如果是经过修改后到达的消息,则无法被解密。如果多个中心节点向同一个地址发送消息,也需要检查who.host.host_id是否受到影响。

信息

已解密的内容:add_post

{
  "who": {
    "user_id": "cu-4f1c2a9e8b7d60",
    "cc_owner": false,
    "post": {"post_id": "post::20261001140322_9f8e7d6c5b4a32"},
    "case": {"case_id": "cc-1a2b3c4d5e6f70", "case_ref_id": "rear-end-2026"},
    "role": {"role_id": "role::staff"},
    "host": {"host_id": "ca-7e6d5c4b3a2f10"}
  },
  "what": {
    "trigger": {"name": "add_post"},
    "content": {
      "new": "Hi Jane, your records request went out today.",
      "type": "app_add_post",
      "kwargs": {"case_id": "cc-1a2b3c4d5e6f70", "case_ref_id": "rear-end-2026"}
    }
  },
  "where": {"location": {"name": "app"}, "module": {"name": "post"}},
  "when": {"datetime": {"timezone": "utc", "datetime": "2026-10-01T14:03:22.123456+0000"}},
  "targets": {"user_ids": ["cu-4f1c2a9e8b7d60"], "cc_user_ids": [], "group_targets": false}
}
场地它包含什么
what.trigger.name上述活动中的事件,来自上面的表格。
what.content.new 或 what.content.old该文本,或者该文件的链接
who.user_id是谁发表了这篇帖子或评论呢?即使后来有人对内容进行了修改或删除,情况又如何呢?
who.post.post_id该帖子是关于一些活动的信息。
who.comment.comment_id关于评论事件的评论
who.comment.post_id该帖子所属的评论链接
who.case.case_id根据API所使用的标识符,该案例的名称是……
who.case.case_ref_id该案例的标签ID标签 ID 您给案例赋予的永久标签,例如 rear-end-2026,也显示为参考 ID,并在导入时使用。
who.role.role_id作者在该案件中的角色,例如role::clients。如果作者已经离开了该案件,则这一信息将缺失。
who.host.host_id你的归宿
when.datetime.datetime当这种情况发生时,时间是以UTC标准计算的。

其他那些区域都是供枢纽自身使用的;无需理会它们。

相关文章

设置信息流活动的 webhook当动态消息、评论或附件被添加、更改或删除时,向您的系统发送消息。集成 · 10 min修复停止发送的 webhook为什么 webhook 在两次投递失败后或处于非活动状态时会停止,以及如何通过再次保存来重新启用它。集成