跳到主要内容

Webhook

Webhook 会在定时导出完成时通知外部系统。该功能由 Exportelier Automation 应用提供，在站点管理员启用 Webhook 分发之前始终处于禁用状态。

可用的 Webhook 类型​

  • Slack 传入 Webhook —— 以普通频道消息的形式发布导出摘要。
  • Microsoft Teams 工作流 Webhook —— 通过客户自建的 Teams 工作流发布 Adaptive Card 1.2。

Webhook 配置 Webhook 端点设置，显示类型、脱敏引用与状态。

Webhook 发送链接，但不会将文件上传到 Slack 或 Teams

Webhook 绝不会把生成的 PDF、DOCX 或 Markdown 文件附加到服务商消息中。默认情况下，只包含一个工作项的计划导出会链接到该 Jira 工作项。如果同一次运行还成功完成了 Jira 附件目标，消息也会链接到这个已生成的附件。两个链接都保留在 Jira 内，接收者仍需具有相应的 Jira 访问权限。

消息内容是什么样的​

两种渠道发送的摘要行是相同的：

Exportelier export "Weekly sprint report": sprint-report-2026-09-01.pdf (14 issues)
  • Slack 接收摘要，并在可用时显示可点击的打开 Jira 工作项与打开文档链接。
  • Teams 接收一张 Adaptive Card 1.2，其标题为 Exportelier export: <计划任务名称>、正文为同一条摘要行，并在可用时显示相应的 OpenUrl 操作。

多工作项导出不会包含 Jira 工作项链接。只有 Jira 附件目标先成功后才会包含文档链接。端点的测试消息不会包含这两个链接，因为测试不会导出或附加文档。

设置​

两种渠道都遵循相同的三个环节：先启用一次分发，然后注册端点，最后在计划任务中选择它。

1. 启用 Webhook 分发​

在 Exportelier Automation 中打开设置 → 外部分发，并开启启用 Webhook 分发。此时会出现一个确认对话框 —— 这正是站点管理员明确接受数据将离开 Atlassian 的地方。

在该开关打开之前，所有计划任务上的 Webhook 分发目标都会保持灰显，也不会发送任何内容。

2a. 注册 Slack 传入 Webhook​

Slack 通过 Slack 应用签发传入 Webhook URL：

  1. 打开 api.slack.com/apps，选择 Create New App → From scratch。为其命名（例如 Exportelier），并选择目标工作区。
  2. 在应用侧边栏中打开 Incoming Webhooks，并开启 Activate Incoming Webhooks。
  3. 点击 Add New Webhook to Workspace，选择应接收通知的频道，然后点击 Allow 确认。
  4. 复制生成的 Webhook URL。它的形式为 https://hooks.slack.com/services/T…/B…/…。请像对待密码一样对待它：任何持有它的人都可以向该频道发消息。
  5. 在 Exportelier Automation 中进入设置 → Webhook 端点，将渠道设为 Slack 传入 Webhook，把该 URL 粘贴到端点中，然后点击添加端点。

Exportelier 仅接受主机名为 hooks.slack.com 的 HTTPS URL。消息会以你所创建的 Slack 应用的名称和图标显示；这两者可在 Slack 的 Basic Information → Display Information 中修改。

不要使用 Workflow Builder 触发器 URL

Slack Workflow Builder 也会签发 hooks.slack.com 的 URL，但它们形如 https://hooks.slack.com/triggers/…，并且期望的是该工作流的具名变量，而不是 text 字段。Exportelier 的主机检查会接受这类 URL，但频道中不会出现可读的消息。请按上文所述，使用来自 Slack 应用的传入 Webhook（/services/…）。

2b. 注册 Microsoft Teams 工作流 Webhook​

Microsoft 已于 2026 年 5 月停用 Office 365 Connector Webhook。因此 Exportelier 只接受来自 Microsoft Teams Workflows 的新 Teams 端点。

  1. 在目标 Teams 频道中，打开 More options (…) → Workflows。
  2. 选择 Send webhook alerts to a channel。这是 Anyone 模板。如果你从零开始搭建工作流，请选择触发器 When a Teams webhook request is received，并将其认证类型设为 Anyone。
  3. 认证将拥有该工作流的 Microsoft 账户，选择团队与频道，然后添加工作流。Microsoft 声明这些 Teams Webhook 模板不需要高级版许可证。
  4. 复制生成的 URL。请像对待密码一样对待它：任何拥有这个已签名 URL 的人都可以触发该工作流。
  5. 在 Exportelier Automation 中进入设置 → Webhook 端点，将渠道设为 Microsoft Teams 工作流 Webhook，把该 URL 粘贴到端点中，然后点击添加端点。

受支持的 URL 使用 HTTPS，且位于 environment.api.powerplatform.com 或 logic.azure.com 的子域名下。Exportelier 不会发送 OAuth 标头；请求由 Anyone 类型的机密 URL 授权。

消息会以 Microsoft 默认的 Workflows 机器人身份显示。对于这类 Webhook 消息，Microsoft 不支持自定义机器人名称或图标。

已停用的 Office 365 Connector

已保存的 *.webhook.office.com 端点仍会显示为需要处理，以免计划任务被悄然改变。请先创建并测试一个新的工作流端点，更新所有受影响的计划任务，然后再删除这个旧端点。旧端点无法用于新的计划任务，并会在发出任何请求之前于本地失败。

2c. 验证端点​

每个已注册的端点都带有一个测试按钮。它会发送一条固定消息 ——

Exportelier test message: this webhook endpoint is configured correctly. No export was generated.

—— 该消息会经过与计划任务运行完全相同的出站网关、已存储的密钥与载荷构造器，因此测试通过证明的是整条分发链路可用，而不仅仅是 URL 格式正确。成功时该行会显示已送达；失败时失败原因会显示在表格上方，并与下文的疑难解答列表相对应。

在 Webhook 分发关闭时，该按钮会灰显，因为此时不会发送任何内容。

3. 在计划任务中选择该端点​

打开计划任务，编辑需要发送通知的计划任务，添加 Webhook 分发目标。先选择渠道，再选择已存储的端点 —— 端点按其脱敏引用列出，因为保存之后 URL 本身绝不会再返回到浏览器。

两个链接选项默认开启，并可分别关闭。一个计划任务可以组合多个目标：同一次运行既可以把文档附加到 Jira 工作项，也可以发送 Webhook 通知。无论显示顺序如何，Exportelier 都会先完成附件目标，再发送请求文档链接的 Webhook。

疑难解答​

没有立刻收到消息。 Exportelier Automation 每五分钟检查一次到期的计划任务，因此分发可能比设定时间最多延迟五分钟。若想不等待运行就检查某个端点，请使用设置 → Webhook 端点下的测试按钮 —— 它返回的提示与计划任务运行时完全一致。

查看上一次运行的结果。 计划任务列表中有一列上次执行，状态为成功、部分成功或执行失败，并会显示失败原因。已生成文档但未能发送 Webhook 的运行会被报告为部分成功。

提示信息含义
Webhook 分发已被管理员禁用。设置 → 外部分发中的启用 Webhook 分发处于关闭状态。
未配置 Webhook 端点。在仍有计划任务引用该端点时，它已在 Exportelier 中被吊销。请重新注册并在计划任务中重新选择。
已存储的密钥与该 Webhook 渠道不匹配。计划任务的渠道被切换到了另一家服务商，却没有选择相匹配的端点。
Webhook 端点拒绝了该请求。服务商返回了错误 —— 通常是 Slack 中已被吊销的 Webhook，或是被关闭、删除的 Teams 工作流。请在服务商一侧创建新的端点。
Slack Webhook 必须使用 hooks.slack.com 的 https URL。该 URL 在保存时被拒绝。请从 Slack 应用的 Incoming Webhooks 页面重新复制。
此 Microsoft Teams 连接器已不再受支持。这是已停用的 *.webhook.office.com 连接器。请按上文所述替换为工作流端点。

频道中完全没有消息，但运行显示成功。 Slack 与 Teams 都会在消息呈现之前就返回 200。请确认该 Webhook 仍绑定在你预期的频道上 —— 在 Slack 中查看 Incoming Webhooks，在 Teams 中查看 Workflows。

可靠性与安全​

  • Webhook 分发默认关闭，需要管理员明确确认才能启用。
  • 端点 URL 以加密的 Forge 密钥形式存储，保存之后绝不会返回到浏览器，只会以脱敏引用的形式显示。切勿把它们写入工单、截图或日志。
  • 开启链接选项会把 Jira 站点地址发送给外部服务商；对于单工作项导出，还会发送工作项键。生成的 URL 不含凭据或签名查询参数，仍然需要 Jira 身份验证和相应权限。
  • 请求在 10 秒后超时，且仅在网络故障、HTTP 429 或 5xx 时重试一次。4xx 响应是最终结果，不会重试。
  • 服务商返回成功响应（包括 HTTP 200 或 202）即将该目标标记为已送达。

有关出站流量如何隔离，参见安全架构；有关以编程方式触发，参见 API 页面。