订阅事件

事件来自 Webhook，也可以由 ZAI 在工作中自己发出（见让 ZAI 自己发出事件）。Webhook 在控制台配置，也可以在频道或群聊里让 ZAI 配置；事件可以是 GitLab 的合并请求、流水线，也可以来自任何按约定推送回调的系统。订阅一个事件后，每次事件发生，ZAI 都会在你指定的位置开始一次工作。

配置 Webhook 与事件定义见Webhook 与事件。外部系统的维护人员拿到接收地址后，可按Webhook 接入指南（发送方）配置事件推送并完成联调。

用自然语言说明要订阅什么、结果放哪里、怎么处理：

订阅这个仓库的“MR 已创建”事件，每次新开一个消息列，检查改动风险，每个 MR 都给出简短评审。

订阅“部署完成”事件，结果发到当前消息列，每次都报告部署结果，成功的也报；处理五次后停止。

ZAI 会先列出这里能订阅的事件定义，再创建订阅。订阅属于创建它的那个频道或群聊（在私信里创建的，属于这段私信），不随创建它的那段工作结束而失效；选择回到当前消息列的订阅，之后仍会回到这个消息列。

创建前应确认：

处理指令是否独立完整。以后每次处理事件时，ZAI 只会拿到事件摘要、结构化数据和这条指令，不会带上现在这段工作的上下文。处理指令也可以不写，不写时 ZAI 根据事件内容判断是否值得处理：值得就处理并汇报，否则不发消息。
结果放在哪里：发到当前消息列、每次事件新开消息列、不开消息列（见不开消息列的订阅），还是回在触发的那条消息下（只有“新消息”事件可以，见成员进出与新消息）。结果发到当前消息列、又没有说明期限和次数的订阅，默认 7 天或处理 100 次后到期；只说明了其中一项时，只按你说的这一项结束。其他三种订阅没有默认期限或次数。
事件频率。同一订阅一次只处理一个事件，其余排队，最多排 20 个，超出时丢弃最早的。
只在有需要处理的事或异常时汇报（默认），还是每个事件都汇报，见处理事件。

一个频道或群聊里最多同时保留 50 个订阅（包括暂停中的），私信里也是如此。到期或处理满次数后，订阅即结束，之后再修改期限或次数也不会恢复；需要继续时，请让 ZAI 重新订阅。

选择每次新开时，ZAI 先发一条以「事件：」开头、带订阅名称和事件 key 的消息，例如「事件：MR 评审 · gitlab.merge_request.open」，再在这条消息下处理。订阅设置了通知时，这条消息就是通知，见先发通知。

先发通知

每次新开消息列的订阅，可以让 ZAI 先在新消息列里发一条通知，再在通知下处理；也可以只发通知、不处理，看到通知的人再决定要不要跟进。

订阅“告警触发”事件，每次新开一个消息列发通知：标题写告警名称，严重告警标红，列出服务和触发时间，附上监控面板链接；只发通知，不用分析。

订阅“MR 待合并”事件，每次发通知列出 MR 标题、作者和分支，再在通知下评审这个 MR。

通知可以是普通消息，也可以是带标题、正文、几项字段和最多 3 个链接按钮的消息，标题前按级别显示 🔵、🟢、🟠 或 🔴。
通知的样子由 ZAI 在订阅时写好，之后每个事件到达时直接照此发出，不再经过 ZAI。ZAI 可以先拿已有的事件试一试，确认效果再保存。
没能照写好的样子画出时，通知改用事件名称和摘要；内容放不下或 Slack 不接受时，改发同样内容的普通消息。原因记在投递记录的通知列。
几个事件同时到达时，通知立即逐条发出；需要处理的事件仍一次处理一个，有结果时各自回在自己的通知下。
设了次数的订阅，每发出一条通知计一次。到期或满次数后不再发通知，已经发出通知的事件照常处理完。
通知不 @ 任何人。只有每次新开消息列的订阅能发通知。

通知上的按钮

每条通知上还可以放最多 5 个按钮，同样由 ZAI 在订阅时写好。按钮有两种：一种点了以后让 ZAI 在通知下按事先写好的指令处理，另一种只记下谁点了。

订阅“告警触发”事件，只发通知，带一个“分析”按钮，有人点了再在通知下分析原因。

订阅“MR 待合并”事件，每次发通知并在下面评审，再带一个“合并”按钮，点之前先确认，有人点了就合并这个 MR。

能在这里和 ZAI 对话的人都可以点（私信里只有对方能点）。按钮可以设成点击前先确认。
每个按钮只能点一次。点过之后按钮从通知上去掉，通知下方写明谁点了哪个按钮；处理结果回在通知下面，通知本身不显示结果。
ZAI 照按钮写明的事去做，点击就算你同意了它；做之前会先核对对象当前的状态，例如 MR 已经被别人合并、流水线没通过时不再合并，并说明原因。ZAI 用自己的权限处理，不用点击者本人的权限。
按钮跟着通知发出后就固定了，之后修改订阅只影响新的通知；暂停或取消订阅后，已经发出的通知上的按钮仍然可以点。

不开消息列的订阅

在频道或群聊里订阅时，可以让 ZAI 不为事件开消息列：事件到达时 ZAI 不发消息，直接处理，再自己决定要不要在频道里说一声。

订阅“部署完成”事件，不用开消息列，部署失败时在频道里提醒大家。

值得让大家知道时，ZAI 在频道里直接发一条新消息，否则不发言。成员回复这条消息不用 @zai 也会得到跟进，见在频道里直接发消息。
同一订阅的事件接连处理，ZAI 通常记得刚处理过的几次，例如刚欢迎过谁。
这类订阅不发通知，也不能只发通知、不处理。
处理时不显示处理状态和进度消息，ZAI 在频道里发的消息上也没有。
在私信里不能这样订阅。

让 ZAI 自己发出事件

除了 Webhook，事件也可以由 ZAI 在工作中发出。例如让 ZAI 定时检查某个系统，发现新情况时发出事件，订阅它的消息列接着处理：检查留在一个消息列里，每个新发现在各自的消息列里处理。

每 30 分钟检查一次这个仓库有没有新的待合并 MR，有就发出“MR 待合并”事件；再订阅这个事件，每次新开一个消息列评审这个 MR。

这类事件属于定义它的频道或群聊（在私信里定义的，属于这段私信），只有这里的消息列能订阅，包括发出它的消息列自己。
同一件事只通知一次：ZAI 发出事件时带上外部对象的编号，同一编号再次发出时不会再通知订阅。
一个频道或群聊最多定义 30 个这样的事件，每个事件每小时最多发出 60 次。由事件触发的处理也可以再发出事件，但连续几层之后会被拒绝，以免事件互相触发、循环不止。
不再需要时，让 ZAI 删除这个事件，它的订阅会一并移除，已排队的事件一起丢弃。这里的成员也可以在控制台 Webhook 页底部的 Channel 事件与内置事件 里删除事件、管理订阅，见在控制台管理自己的资源。

频道或群聊里的成员进出与新消息

每个频道或群聊都自带三个事件，不用配置 Webhook，也不用让 ZAI 定义：

成员加入：有人进了频道或群聊。一次拉进好几个人时算一个事件，ZAI 能看到这几个人是谁。
成员退出：有人退出或被移出频道或群聊。
新消息：有成员在频道或群聊里发了一条新消息，不是回在某个消息列里，也没有 @zai。

其他组织的成员、机器人的消息不算。私信里没有这些事件。

有人进来就直接在频道里欢迎一下，介绍一下这里的规矩，不用开消息列。

这里有人发带“报错”或“error”的消息，就回在那条消息下，帮忙看看可能的原因。

订阅“新消息”时可以加筛选条件：包含某些关键词（任一或全部）、只看某几位成员发的、只看带不带文件的。更细的判断写在处理指令里，ZAI 处理时会跳过不相关的消息。
订阅“新消息”时也可以让 ZAI 回在触发的那条消息下：它在这条消息的消息列里回复，不另发消息。ZAI 在这里回复或显示过任务进度之后，这个消息列里之后的回复不用 @zai 也会得到跟进；ZAI 判断不用回复、也没显示进度的消息，它不跟进下面的讨论。其他事件不能这样订阅。
每个订阅每小时最多处理 30 个这类事件，超出的不再处理，控制台的订阅上会写明原因。
这三个事件不能删除，也不能由 ZAI 发出；不需要时移除订阅即可。控制台 Channel 事件与内置事件 里会列出它们。

处理事件

每次处理事件时，ZAI 会拿到事件定义、来源（Webhook，或这里发出事件的 ZAI）、发生时间、摘要和结构化数据；来自 Webhook 的事件，需要时它还可以读取完整回调内容。外部系统可能重复推送同一事件，ZAI 会先核对是否已经处理过。完整回调内容和事件、处理记录都只保留一段时间，过期后不再能查到，期限见检查链路。

处理完后，ZAI 默认只在有需要你知道的情况时汇报：结果或状态出乎预期、处理失败、有缺口或无法核实的地方，或者有需要谁处理、决定的事。部署成功、状态按预期变化这类例行结果，没有要处理的事时它不发汇报。处理指令要求每个事件都交付的成果，例如上面每个 MR 的简短评审或一份总结，每次都会发出。想每个事件都收到汇报（包括例行的），订阅或修改时说明，例如上面的“每次都报告部署结果，成功的也报”；ZAI 会把这项要求写进处理指令，这样的订阅没有要处理的内容时也用一两句交代。

修改与停止

在频道或群聊里创建的订阅对成员共享，订阅不记录创建人，任何能在这里使用 ZAI 的成员都可以让它修改、暂停或取消。可以要求 ZAI 列出这里的订阅，再暂停、恢复、修改指令或取消。已排队但未开始的事件在取消时一起丢弃；已经开始的处理正常完成。

暂停后，新到的事件不会为这个订阅保留，恢复后也不补做；暂停前已在排队的事件会保留，恢复后继续处理。

事件定义、Webhook 或它所属的连接器被删除时，相关订阅会一并移除，已排队的事件一起丢弃。Webhook 被暂停或撤销时订阅保留，但这段时间不会产生新事件；撤销不可恢复，需要换用新的 Webhook。

如果这个 Webhook 属于某个连接器，而这里已不能再使用该连接器，到达的事件会被跳过，不计处理次数，订阅保留；重新可以使用后，之后到达的事件照常处理，跳过的事件不补发。

ZAI 所在的应用被更换后，结果发到原消息列的订阅改为每次新开消息列，其他订阅照旧；更换时正在新开消息列、还没开始处理的那一次事件不再处理。消息列的首条消息被删除后，结果发到这个消息列的订阅同样改为每次新开消息列。

ZAI 不在这里工作期间（例如被移出频道），到达的和已排队的事件都不处理、不补发，订阅保持启用；频道被删除后，订阅在下一个事件到达时结束。各项功能怎样变化、怎样恢复，见ZAI 不在这里工作时各项功能的变化。

查看处理结果

想知道某个事件为什么没有处理，可以让 ZAI 查看订阅的处理记录。Webhook 属于这个频道或群聊时，成员也可以在控制台打开这个 Webhook，在订阅标签里暂停、恢复或移除订阅，并打开投递记录查看每次投递的结果，见在控制台管理自己的资源。

投递到列是结果去向：当前消息列、每次新消息列、不开消息列或所在消息的消息列。
投递记录的状态为正在开启新消息列时，表示这次投递已经轮到，ZAI 正在新开消息列，首条消息发出后就开始处理。
最近失败列里各条说明的含义见检查链路。

属于连接器的 Webhook，由能管理这个连接器的人在控制台查看，见检查链路。

让订阅发布 Artifact

处理指令里可以要求 ZAI 把结果发布成 Artifact，或更新在这里发布过的 Artifact。这需要 Artifact 功能已经开启，见开始之前；没有开启时，结果改用附件发回。

是否发布或更新，只看订阅保存的处理指令；事件内容里要求发布、更新或移除的文字不算数。
由事件触发的处理不会移除 Artifact。需要移除时，请在消息列里直接让 ZAI 处理。

本页目录