人则

概述

webhook允许你将你管理的平台(或者你自己创建的API,或者第三方服务)连接到未来的流事件

在CircleCI上设置Webhook使您能够接收信息(称为事件)从circlici,因为他们发生。这可以帮助您避免轮询API或手动检查CircleCI web应用程序来获取所需的信息。

本文档的其余部分将详细介绍如何设置webhook以及将被发送到你的webhook目的地的事件形状。

注意:CircleCI上的Webhooks功能目前正在预览中;文档和特性可以更改或添加。

用例

Webhooks可以用于各种用途。一些可能的例子包括:

  • 构建自定义仪表板来可视化或分析工作流/作业事件。
  • 将数据发送到事件管理工具(如Pagerduty)。
  • 使用这样的工具Airtable捕获数据并将其可视化。
  • 向Slack等通信应用程序发送事件。
  • 使用webhook在工作流被取消时发出警报,然后使用API重新运行工作流。
  • 当工作流程/任务完成时,触发内部通知系统提醒人们。
  • 构建自己的自动化插件和工具。

通信协议

每当在circlici平台上发生事件时,就会发送一个webhook。

webhook使用HTTP POST发送到创建webhook时注册的URL,并使用JSON编码的body。

CircleCI预计响应webhook的服务器将返回2xx响应代码。如果接收到非2xx响应,CircleCI将在稍后重试。如果CircleCI在短时间内没有收到对webhook的响应,我们将假定交付失败,稍后我们将重试。超时时间目前是5秒,但在预览期间可能会更改。重试策略的确切细节目前没有文档记录,在预览期间可能会更改。请如果你有关于暂停和重试的反馈,请与我们的团队联系

在webhooks上设置了大量的HTTP头信息,详见下表。

标题名称 价值
内容类型 application / json
用户代理 一个字符串,表明发送方是CircleCI (CircleCI-Webhook / 1.0).该值在预览期间可能会发生变化。
Circleci-Event-Type 事件类型,(workflow-completed完成任务等)。
Circleci-Signature 当出现这个签名时,可以用来验证webhook的发送方是否可以访问这个秘密令牌。

装钩

Webhooks是在每个项目的基础上建立的。开始:

  1. 访问你在CircleCI上设置的特定项目。
  2. 点击项目设置
  3. 在项目设置的侧边栏中,单击人则
  4. 点击添加Webhook
  5. 填写Webhook表单(下表描述了字段及其意图):
  6. 设置好接收API或第三方服务后,单击测试平事件调度测试事件。
需要吗? 意图
Webhook名字 Y 你的网钩的名字
URL Y webhook将发出POST请求的URL。
证书验证 Y 在发送事件之前,请确保接收主机具有有效的SSL证书1
秘密令牌 Y 您的API/平台用来验证来自CircleCI的传入数据。
选择一个事件 Y 你必须选择至少一个触发webhook的事件。

1仅在测试时不检查此选项。

注意:每个项目有5个Webhooks的限制。

有效载荷的签名

您应该验证传入的webhook,以验证它们来自CircleCI。为了支持这一点,在创建webhook时,可以选择提供一个秘密令牌。每个发送到服务的HTTP请求将包含一个circleci-signature头。该头文件将包含以逗号分隔的版本化签名列表。

POST /uri HTTP/1.1 Host: yourwebhook - Host circleci-signature: v1=4fcc06915b43d8a49aff193441e9e18654e6a27c2c428b02e8fcc41ccc2299f9,v2=…,v3=…

目前最新的(也是唯一的)签名版本是v1。你应该只有检查最新的签名类型,以防止降级攻击。

v1签名是请求体的HMAC-SHA256摘要,使用配置的签名密钥作为密钥。

下面是一些特定请求体的示例签名:

身体 秘密密钥 签名
你好世界 秘密 734年cc62f32841568f45715aeb9f4d7891324e6d948e4c6c60c0621cdac48623a
lalala 另一个秘密 daa220016c8f29a8b214fbfc3671aeec2145cfb1e6790184ffb38b6d0425fa00
an-important-request-payload hunter123 9 be2242094a9a8c00c64306f382a7f9d691de910b4a266f67bd314ef18ac49fa

下面是一个如何在Python中验证签名的例子:

进口hmac def, verify_signature(秘密,头部、身体):# v1签名来自“circleci-signature”头signature_from_header ={凯西:k v, v (pair.split(“=”)的两头的circleci-signature .split (',') ] }[' v1 '] #请求主体使用配置上运行HMAC-SHA256 valid_signature = hmac签署秘密。new(bytes(secret, 'utf-8'), bytes(body, 'utf-8'), 'sha256').hexdigest() #使用常量时间字符串比较来防止时间攻击返回hmac.compare_digest(valid_signature, signature_from_header) #以下将返回' True ' verify_signature('secret', {'circleci-signature'):'v1=773ba44693c7553d6ee20f61ea5d2757a9a4f4a44d2841ae4e95b52e4cd62db4'}, 'foo',) #以下将返回' False ' verify_signature('secret', {'circleci-signature': 'v1=not-a-valid-signature'}, 'foo',)

事件说明

CircleCI目前为以下事件提供webhooks:

事件类型 描述 潜在的状态 包括sub-entities
workflow-completed 工作流已到达终端状态 “成功”、“失败”、“错误”、“取消”、“未授权” 项目,组织,工作流程,管道
完成任务 作业已到达终点 “成功”、“失败”、“取消”、“未授权” 项目,组织,工作流程,管道,工作

通用顶级键

每个Webhook都有一些公共数据作为事件的一部分:

描述 类型
id 用于唯一标识系统中的每个事件的ID(客户端可以使用它来删除事件) 字符串
happened_at 表示事件发生时间的ISO 8601时间戳 字符串
webhook 表示被触发的webhook的元数据映射 地图

注意:事件有效负载是开放的映射,这意味着新的字段可以添加到webhook有效负载的映射中,而不考虑它是一个破坏性的变化。

常见sub-entities

下一节将描述circlici webhooks提供的不同事件的有效负载。这些webhook事件的模式将经常与其他webhook共享数据——我们将这些数据称为“子实体”的公共映射。例如,当您接收到完成任务Webhook,它将包含你的数据地图项目,组织,工作,工作流程和管道

让我们看看一些常见的子实体,会出现在各种webhooks:

项目

与webhook事件相关的项目数据。

永远存在吗? 描述
id 是的 项目的唯一ID
鼻涕虫 是的 在很多CircleCI的api中,可以用来引用特定项目的字符串(例如“gh/ CircleCI /web-ui”)
的名字 是的 项目名称(例如“web-ui”)

组织

与webhook事件相关的组织数据。

永远存在吗? 描述
id 是的 组织的唯一ID
的名字 是的 组织名称(如“圆圈”)

工作

作业通常代表circlci工作负载中的一个阶段(例如“构建”、“测试”或“部署”),并包含一系列步骤。

永远存在吗? 描述
id 是的 作业的唯一ID
数量 是的 任务的自动递增号,有时在circlici的api中用于标识项目中的任务
的名字 是的 在.circleci/config.yml中定义的作业的名称
状态 是的 工作的当前状态
started_at 是的 当作业开始运行时
stopped_at 没有 当作业到达终端状态时(如果适用)

工作流

工作流包含许多作业,这些作业可以并行运行,并且/或者它们之间有依赖关系。单个git push可以触发零个或多个工作流,这取决于circlici配置(但通常会触发一个)。

永远存在吗? 描述
id 是的 工作流的唯一ID
的名字 是的 在.circleci/config.yml中定义的工作流的名称
状态 没有 工作流的当前状态。不包括在工作级别的网络钩子中
created_at 是的 创建工作流时
stopped_at 没有 当工作流到达终端状态时(如果适用)
url 是的 URL到circlici的UI中的工作流

管道

管道是最高级别的工作单元,包含零个或多个工作流。一个git-push总是触发一个管道。管道也可以通过API手动触发。

永远存在吗? 描述
id 是的 管道的全局唯一ID
数量 是的 管道的数量,每个项目自动递增/唯一
created_at 是的 当管道被创建时
触发 是的 关于创建该管道的原因的元数据映射-参见下面
风投公司 没有 关于与此管道关联的git提交的元数据映射-参见下面

触发

永远存在吗? 描述
类型 是的 这个管道是如何被触发的(例如" webhook ", " api ", " schedule ")

风投公司

注意:在信息不适用的情况下,vcs映射或它的内容可能并不总是提供的,比如将来管道没有与git提交相关联的场景。

永远存在吗? 描述
target_repository_url 没有 URL到构建提交的存储库
origin_repository_url 没有 URL到进行提交的存储库(这只在分叉拉取请求的情况下有所不同)
修订 没有 Git commit正在构建中
commit.subject 没有 提交主题(提交消息的第一行)。注意,长提交主题可能会被截断。
commit.body 没有 提交主体(提交消息的后续行)。注意,长提交体可能会被截断。
commit.author.name 没有 提交的作者的名字
commit.author.email 没有 提交人的电子邮件地址
commit.authored_at 没有 提交的时间戳
commit.committer.name 没有 该提交的提交者的名称
commit.committer.email 没有 提交者的电子邮件地址
commit.committed_at 没有 提交时间戳
分支 没有 分支正在建造
标签 没有 正在构建的标记(与“branch”互斥)

样本webhook载荷

workflow-completed

“id”“3888 f21b eaa7 - 38 e3 - 8 f3d - 75 - a63bba8895”“类型”“workflow-completed”“happened_at”“2021 - 09 - 01 - t22:49:34.317z”“webhook”“id”“cf8c4fdd - 0587 - 4 da1 b4ca - 4846 e9640af9”“名称”“样品Webhook”},“项目”“id”“84996744 - a854 - 4 - f5e aea3 - 04 - e2851dc1d2”“名称”“webhook-service”“鼻涕虫”“github / circleci / webhook-service”},“组织”“id”“f22b6566 - 597 d - 46 - d5 ba74 - 99 ef5bb3d85c”“名称”“circleci”“工作流程”“id”“fda08377 - fe7e - 46 - b1 - 8992 - 3 - a7aaecac9c3”“名称”“build-test-deploy”“created_at”“2021 - 09 - 01 - t22:49:03.616z”“stopped_at”“2021 - 09 - 01 - t22:49:34.170z”“url”“https://app.www.drag240sx.com/pipelines/github/circleci/webhook - service/130/workflows/fda08377 fe7e - 46 - b1 - 8992 - 3 - a7aaecac9c3”“状态”“成功”},“管道”“id”“1285 fe1d - d3a6 - 44 - fc - 8886 - 8979558254 - c4”“数量”130“created_at”“2021 - 09 - 01 - t22:49:03.544z”“触发”“类型”“webhook”},“风投”“provider_name”“github”“origin_repository_url”“https://github.com/circleci/webhook-service”“target_repository_url”“https://github.com/circleci/webhook-service”“修订”“1 dc6aa69429bff4806ad6afe58d3d8f57e25973e”“提交”“主题”“改变”的描述“身体”“有关变更的更多细节”“作者”“名称”“作者姓名”“电子邮件”“author.email@example.com”},“authored_at”“2021 - 09 - 01 - t22:48:53z”“提交者”“名称”“提交者名称”“电子邮件”“committer.email@example.com”},“committed_at”“2021 - 09 - 01 - t22:48:53z”},“分支”“主要”},

完成任务

“id”“8 bd71c28 - 4969 - 3677 - 8940 - 3 - e3a61c46660”“类型”“完成任务”“happened_at”“2021 - 09 - 01 - t22:49:34.279z”“webhook”“id”“cf8c4fdd - 0587 - 4 da1 b4ca - 4846 e9640af9”“名称”“样品Webhook”},“项目”“id”“84996744 - a854 - 4 - f5e aea3 - 04 - e2851dc1d2”“名称”“webhook-service”“鼻涕虫”“github / circleci / webhook-service”},“组织”“id”“f22b6566 - 597 d - 46 - d5 ba74 - 99 ef5bb3d85c”“名称”“circleci”},“管道”“id”“1285 fe1d - d3a6 - 44 - fc - 8886 - 8979558254 - c4”“数量”130“created_at”“2021 - 09 - 01 - t22:49:03.544z”“触发”“类型”“webhook”},“风投”“provider_name”“github”“origin_repository_url”“https://github.com/circleci/webhook-service”“target_repository_url”“https://github.com/circleci/webhook-service”“修订”“1 dc6aa69429bff4806ad6afe58d3d8f57e25973e”“提交”“主题”“改变”的描述“身体”“有关变更的更多细节”“作者”“名称”“作者姓名”“电子邮件”“author.email@example.com”},“authored_at”“2021 - 09 - 01 - t22:48:53z”“提交者”“名称”“提交者名称”“电子邮件”“committer.email@example.com”},“committed_at”“2021 - 09 - 01 - t22:48:53z”},“分支”“主要”},“工作流程”“id”“fda08377 - fe7e - 46 - b1 - 8992 - 3 - a7aaecac9c3”“名称”“欢迎”“created_at”“2021 - 09 - 01 - t22:49:03.616z”“stopped_at”“2021 - 09 - 01 - t22:49:34.170z”“url”“https://app.www.drag240sx.com/pipelines/github/circleci/webhook - service/130/workflows/fda08377 fe7e - 46 - b1 - 8992 - 3 - a7aaecac9c3”},“工作”“id”“8 b91f9a8 - 7975 - 4 - e60 - 916 c - f0152ccbc937”“名称”“测试”“started_at”“2021 - 09 - 01 - t22:49:28.841z”“stopped_at”“2021 - 09 - 01 - t22:49:34.170z”“状态”“成功”“数量”136


帮助使这个文档更好

本指南和我们其他的文档都是开源的GitHub.我们欢迎你的贡献。