概况

通过配置知识库的 Webhooks 开发者能够获取到指定知识库下所有文档的发布状态。只要该知识库下的文档被发布或更新，会按需触发该知识库下所配置的 Webhooks。

目前仅 知识库内文档格式 支持配置 Webhooks。

⚠️ ： 知识库 配置了 「自动发布」功能后，文档的 更新/推送 操作暂不会发送机器人通知。

「自动发布」功能具体可以查阅 ： 此处为语雀文档，点击链接查看：https://www.yuque.com/yuque/blog/nyb4v9

配置方式

在 知识库 -> 设置 -> 开发者设置 页面，会出现 Webhooks 配置地址。

确保 WebHook 配置的 URL 地址能够被语雀访问到，即要求它能够被互联网网络访问到。

触发条件

支持2种触发条件：

• 所有更新触发：该知识库下的任何一篇文档的更新都会触发 Webhooks

• 仅主动推送更新触发：只在文档发布或更新的时候勾选了「文档有较大更新，推送给关注人」才会触 Webhooks

  
  

本地开发环境调试

Webhooks 的触发请求是由语雀的服务端发起的，所以你在本地开发环境接入实现 Webhooks 的时候，你可能需要一些额外的工具，将你本地的 HTTP 服务暴露在外网。这样语雀才能请求到。

我们推荐 ngrok 这个工具，安装帮助可参考官方网站：https://ngrok.com

如何使用

启动你的应用 HTTP Server:

$ rails s
Listening on http://localhost:3000

使用 ngrok 将 localhost:3000 暴露在外网：

$ ngrok http 3000
ngrok by @inconshreveable                                                       
                                                                                
Session Status                online                                            
Session Expires               7 hours, 59 minutes                               
Update                        update available (version 2.2.8, Ctrl-U to update)
Version                       2.2.4                                             
Region                        United States (us)                                
Web Interface                 http://127.0.0.1:4040                             
Forwarding                    http://bcb8c93a.ngrok.io -> localhost:3000        
Forwarding                    https://bcb8c93a.ngrok.io -> localhost:3000

现在你有 http://bcb8c93a.ngrok.io 这样一个可以在外部网络访问的地址了。

你可以将它配置在语雀的 Webhooks 界面，例如：

语雀回调 Webhooks URL 方式

语雀会使用 HTTP POST 请求 Webhooks URL，具体的 body 是一个 JSON 数据结构，里面包含的 data 数据定义是 DocDetailSerializer，示例如下：

POST http://someone.com/yuque/webhook

{
  "data": DocDetailSerializer
}

除了 DocDetailSerializer 中的数据之外，请求 body 中还扩展了三个字段：

• path : 文档的完整访问路径（不包括域名）
• action_type : 值有 publish - 发布、 update - 更新、 delete - 删除

• publish : 文档是否为第一次发布，第一次发布时为 true


只有首次文档的发布 publish = true， action_type = 'publish' 之后的发布是更新 publish = false ， action_type = 'update'。

钉钉机器人

语雀 Webhooks 对钉钉自定义机器人做了数据适配，如果添加的 Webhooks URL 是钉钉自定义机器人地址，那么会以 钉钉 link 消息格式发送该知识库的文档 发布 和 更新 信息给机器人。由于钉钉开启了机器人的安全设置，需要在“自定义关键词”中添加“语雀”。

（配置截图）

（钉钉上显示效果）