概况


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


目前仅 知识库 支持配置 Webhooks。



配置方式


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




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



触发条件


支持2种触发条件:




本地开发环境调试


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


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


如何使用


启动你的应用 HTTP Server:


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


使用 ngroklocalhost: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 中还扩展了三个字段:



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



钉钉机器人


语雀 Webhooks钉钉自定义机器人做了数据适配,如果添加的 Webhooks URL 是钉钉自定义机器人地址,那么会以 钉钉 link 消息格式发送该知识库的文档 发布 和 更新 信息给机器人。


(配置截图



钉钉上显示效果)