Webhooks：架构变更的实时通知

上周有一个团队告诉我，他们在Archyl中重命名了一个核心系统——在整个C4模型中把"UserService"改成了"AccountService"，更新了所有关系，重写了ADR。干净、彻底的工作。问题是什么？依赖这个系统的平台团队四天后才发现，那时他们的部署流水线引用了一个已经不存在的名称。

没有人通知他们。不是因为任何人疏忽——而是根本没有这样的机制。架构文档通常是拉取模式。你主动去看图表，你主动去读ADR。如果你不去看，你就不会知道。

这和CI/CD通知成为标准之前困扰软件开发的模式如出一辙。代码变更曾经是你拉取main分支时才会发现的事情。如今，每次合并、每次构建失败、每次部署都会在某处触发通知。架构变更理应享受同样的待遇。

为你的架构推送通知

Archyl现在支持webhooks。当你的C4模型中发生变更——系统被创建、容器被删除、关系被更新、版本发布——Archyl会向你配置的任何端点发送HTTP POST请求，包含一个JSON载荷，精确描述发生了什么。

理念很简单：你的架构是一个活的系统。人和工具应该能够订阅它的变更，就像订阅部署事件或Pull Request通知一样。不用再问"有什么变化吗？"，答案会主动找到你。

44种事件类型

我们不想发布一个只覆盖半个模型的通知系统。Webhooks覆盖了Archyl追踪的所有内容：

C4元素 — 系统、容器、组件和代码元素的创建、更新和删除。你架构模型的核心。

关系 — 当元素之间的连接被创建、修改或移除时。这通常是最重要的信号——两个系统之间的新依赖关系是多个团队都需要知道的那种变更。

ADR与文档 — 架构决策记录和项目文档的创建、更新或删除。当有人写了一份新的ADR解释为什么团队要从REST迁移到gRPC时，受影响的人应该立即得到通知，而不是三个迭代之后。

流程 — 用户流程和系统流程的变更。新流程、更新的步骤、删除的流程。

覆盖层 — 图表上视觉分组的变更。

发布 — 跨环境的部署事件。结合发布管理，这为你提供了完整的基于推送的部署通知流水线。

请求 — 架构变更请求的提交、审核或合并。

API契约与事件通道 — 与架构关联的规范变更和异步消息更新。

发现与洞察 — AI驱动的发现完成和新的架构洞察。

总共四十四种事件类型。你挑选你关心的——订阅全部，或者只选择对你工作流重要的五个事件。

工作原理

设置一个webhook大约只需三十秒。

给它一个名称（描述性的——"Slack通知"、"审计日志同步"、"CI触发器"）。提供一个URL——任何能接收POST请求的HTTP端点。可选地设置一个用于签名验证的密钥。然后选择哪些事件应该触发它。

你还可以将webhook限定到特定项目。一个在所有项目的每次变更时都触发的组织级webhook对审计日志很有用。一个只在支付系统发布事件时才触发的项目级webhook对拥有它的团队很有用。

当匹配的事件发生时，Archyl会向你的URL发送HTTP POST请求，JSON载荷包含：

事件类型 — 44种事件中的哪一个触发了此次投递
实体 — 发生变更的元素的完整详情
操作者 — 谁做了这个变更（用户ID、姓名、邮箱）
项目 — 这发生在哪个项目中
时间戳 — 变更发生的时间
组织 — 这属于哪个组织

载荷为你提供了响应变更所需的一切——展示它、记录它、触发流水线，或同步到其他系统。

安全性：HMAC-SHA256签名

每个webhook请求都包含一个X-Archyl-Signature头，格式为sha256=<十六进制摘要>——使用你的密钥对原始请求体计算的HMAC-SHA256哈希值。你还会收到X-Archyl-Event（事件类型）和User-Agent: Archyl-Webhook/1.0头，以便你识别请求来源。

在接收端，你去掉sha256=前缀，用你保存的密钥对原始请求体字节重新计算HMAC-SHA256哈希值，然后使用恒定时间比较进行校验。如果匹配，请求是可信的。如果不匹配，有人在向你发送伪造的事件。

这与GitHub、Stripe以及大多数webhook提供商使用的签名方案相同。它简单、广为人知，且在任何语言中都易于实现。不需要OAuth流程、不需要令牌轮换、不需要证书管理。只需一个共享密钥和一个哈希值。请参阅webhook文档获取Go、Node.js和Python的完整验证示例。

如果你不设置密钥，签名头将被省略。对于VPN背后的内部端点来说没问题。不建议用于任何暴露在互联网上的端点。

你可以用它构建什么

最明显的用例是聊天通知。Slack、Microsoft Teams和Discord都支持传入webhooks——将它们的URL粘贴到Archyl中，选择你关心的事件，架构变更就会开始出现在你的频道中。一个新系统被添加了。一份ADR被批准了。一个版本发布到了生产环境。你的团队不用打开Archyl就能看到。

但通知只是开始。

同步到外部系统 — 将架构变更推送到CMDB、内部Wiki或服务目录。当Archyl中的容器被重命名时，你的服务目录自动更新。

触发CI/CD流水线 — 当架构变更请求被合并时，启动一个流水线来重新生成基础设施配置、更新Terraform模块，或验证实际部署是否与文档中的架构一致。

审计追踪 — 将每个事件转发到外部日志系统——Elasticsearch、Splunk或一个简单的只追加数据库。Archyl中七天的投递历史对调试很有用；一个永久的外部日志对合规很有用。

自定义仪表板 — 构建一个内部仪表板，实时响应架构事件。追踪架构变更的频率、哪些团队最活跃、哪些系统最不稳定。

关键在于，webhooks将Archyl变成了一个事件源。你的架构模型变成了其他系统可以订阅、响应并在其之上构建的东西。

投递追踪

每次webhook投递都会被记录。你可以查看任何webhook的完整历史：哪个事件触发了它、发送的请求载荷、响应状态码、响应体，以及发送时间和收到响应的时间戳。

投递记录保留七天。足够长以便调试集成问题，又足够短以避免无限期存储你端点的响应体。

当投递失败时——你的服务器返回500、超时、DNS解析错误——它会以红色状态显示。你可以检查错误、修复端点，然后一键重试。重试会发送完全相同的载荷，因此你的端点处理的就是原始事件，就像第一次成功了一样。

没有自动重试。我们考虑过指数退避，但在实践中，大多数webhook失败要么是暂时性的（你的服务器正在重启），要么是结构性的（URL错了）。对于暂时性失败，手动重试按钮比等待退避更快。对于结构性失败，自动重试只会产生噪音。

开始使用

前往组织设置 > Webhooks
点击创建Webhook
输入名称，粘贴端点URL，设置密钥
选择你要订阅的事件
可选择筛选特定项目
点击发送测试验证端点能收到载荷
保存，即刻生效

测试投递会发送一个带有示例载荷的ping事件，这样你可以确认端点可达、密钥配置正确、处理程序能正常解析JSON。在订阅真实事件之前先做这一步。

架构即事件流

我们一直在朝着这样一个愿景构建：架构文档不是一个静态产物——它是你开发工作流中活的、连接的一部分。Marketplace集成将外部数据引入你的架构。Webhooks将架构数据推送到你的工具。

两者的结合非常强大。你的架构工作区不再只是一个查看图表的地方。它是一个枢纽，从监控工具接收运营数据，同时向通信和自动化工具发送变更事件。数据双向流动。

没有人看的架构文档毫无用处。在重要时刻主动通知你的架构文档——那才是基础设施。

想了解其他功能如何将架构连接到你的工作流？查看Marketplace集成了解如何在图表上展示实时数据，或发布管理了解如何在C4模型中跟踪部署。