Hugging Face's logo
加入 Hugging Face 社区

并获得增强型文档体验

开始使用

Webhooks

Webhooks 现已公开可用!

Webhooks 是与 MLOps 相关的功能的基础。它们允许您侦听特定存储库或属于特定用户/组织集的所有存储库的新更改(不仅是您的存储库,而且是任何存储库)。

您可以使用它们来自动转换模型、构建社区机器人或为您的模型、数据集和空间构建 CI/CD(以及更多!)。

Webhooks 的文档如下 - 或者您也可以浏览我们的 **指南**,其中展示了一些 Webhooks 的可能用例

创建您的 Webhook

您可以在 Webhooks 设置 中创建新的 Webhooks 并编辑现有 Webhooks

Settings of an individual webhook

Webhooks 可以监视存储库更新、拉取请求、讨论和新评论。甚至可以创建空间来对您的 Webhooks 做出反应!

Webhook 有效负载

注册 Webhook 后,您将通过指定目标 URL 上的 HTTP POST 调用收到新事件的通知。有效负载以 JSON 格式编码。

您可以在 Webhook 设置页面的活动选项卡中查看发送的有效负载历史记录,还可以重播过去的 Webhook 以便于调试

image.png

例如,以下是在打开拉取请求时完整的有效负载

{
  "event": {
    "action": "create",
    "scope": "discussion"
  },
  "repo": {
    "type": "model",
    "name": "openai-community/gpt2",
    "id": "621ffdc036468d709f17434d",
    "private": false,
    "url": {
      "web": "https://huggingface.co/openai-community/gpt2",
      "api": "https://huggingface.co/api/models/openai-community/gpt2"
    },
    "owner": {
      "id": "628b753283ef59b5be89e937"
    }
  },
  "discussion": {
    "id": "6399f58518721fdd27fc9ca9",
    "title": "Update co2 emissions",
    "url": {
      "web": "https://huggingface.co/openai-community/gpt2/discussions/19",
      "api": "https://huggingface.co/api/models/openai-community/gpt2/discussions/19"
    },
    "status": "open",
    "author": {
      "id": "61d2f90c3c2083e1c08af22d"
    },
    "num": 19,
    "isPullRequest": true,
    "changes": {
      "base": "refs/heads/main"
    }
  },
  "comment": {
    "id": "6399f58518721fdd27fc9caa",
    "author": {
      "id": "61d2f90c3c2083e1c08af22d"
    },
    "content": "Add co2 emissions information to the model card",
    "hidden": false,
    "url": {
      "web": "https://huggingface.co/openai-community/gpt2/discussions/19#6399f58518721fdd27fc9caa"
    }
  },
  "webhook": {
    "id": "6390e855e30d9209411de93b",
    "version": 3
  }
}

事件

顶级属性 event 始终指定并用于确定事件的性质。

它有两个子属性:event.actionevent.scope

event.scope 将是以下值之一

  • "repo" - 存储库上的全局事件。关联的 action 的可能值:"create""delete""update""move"
  • "repo.content" - 存储库内容上的事件,例如新的提交或标签。由于新创建的引用/提交,它也会触发新的拉取请求。关联的 action 始终为 "update"
  • "repo.config" - 配置上的事件:更新空间密钥、更新设置、更新 DOI、禁用或启用等。关联的 action 始终为 "update"
  • "discussion" - 创建讨论或拉取请求、更新标题或状态以及合并。关联的 action 的可能值:"create""delete""update"
  • "discussion.comment" - 创建、更新和隐藏评论。关联的 action 的可能值:"create""update"

将来可以添加更多范围。为了处理未知事件,您的 Webhook 处理程序可以将任何范围缩小的操作视为更广泛范围上的 "update" 操作。

例如,如果将来添加了 "repo.config.dois" 范围,则您的 Webhook 处理程序可以将任何具有该范围的事件视为 "repo.config" 范围上的 "update" 操作。

存储库

在当前版本的 Webhooks 中,顶级属性 repo 始终指定,因为事件始终可以与存储库关联。例如,请考虑以下值

"repo": {
	"type": "model",
	"name": "some-user/some-repo",
	"id": "6366c000a2abcdf2fd69a080",
	"private": false,
	"url": {
		"web": "https://huggingface.co/some-user/some-repo",
		"api": "https://huggingface.co/api/models/some-user/some-repo"
	},
	"headSha": "c379e821c9c95d613899e8c4343e4bfee2b0c600",
	"tags": [
		"license:other",
		"has_space"
	],
	"owner": {
		"id": "61d2000c3c2083e1c08af22d"
	}
}

repo.headSha 是存储库的 main 分支上最新提交的 sha。仅当 event.scope"repo" 开头时才会发送,在社区事件(如讨论和评论)中不会发送。

代码更改

在代码更改上,顶级属性 updatedRefs 在存储库事件上指定。它是已更新的引用的数组。这是一个示例值

"updatedRefs": [
  {
    "ref": "refs/heads/main",
    "oldSha": "ce9a4674fa833a68d5a73ec355f0ea95eedd60b7",
    "newSha": "575db8b7a51b6f85eb06eee540738584589f131c"
  },
  {
    "ref": "refs/tags/test",
    "oldSha": null,
    "newSha": "575db8b7a51b6f85eb06eee540738584589f131c"
  }
]

新创建的引用将 oldSha 设置为 null。已删除的引用将 newSha 设置为 null

您可以对特定拉取请求上的新提交、新标签或新分支做出反应。

讨论和拉取请求

顶级属性 discussion 指定在社区事件(讨论和 Pull Request)上。discussion.isPullRequest 属性是一个布尔值,指示讨论是否也是一个 Pull Request(在 Hub 上,PR 是一种特殊的讨论类型)。以下是一个示例值

"discussion": {
	"id": "639885d811ae2bad2b7ba461",
	"title": "Hello!",
	"url": {
		"web": "https://huggingface.co/some-user/some-repo/discussions/3",
		"api": "https://huggingface.co/api/models/some-user/some-repo/discussions/3"
	},
	"status": "open",
	"author": {
		"id": "61d2000c3c2083e1c08af22d"
	},
	"isPullRequest": true,
	"changes": {
		"base": "refs/heads/main"
	}
	"num": 3
}

评论

顶级属性 comment 在创建(包括讨论创建)或更新评论时指定。以下是一个示例值

"comment": {
	"id": "6398872887bfcfb93a306f18",
	"author": {
		"id": "61d2000c3c2083e1c08af22d"
	},
	"content": "This adds an env key",
	"hidden": false,
	"url": {
		"web": "https://huggingface.co/some-user/some-repo/discussions/4#6398872887bfcfb93a306f18"
	}
}

Webhook 密钥

设置 Webhook 密钥有助于确保发送到您的 Webhook 处理程序 URL 的有效负载实际上来自 Hugging Face。

如果为您的 Webhook 设置了密钥,它将作为 X-Webhook-Secret HTTP 标头随每个请求一起发送。仅支持 ASCII 字符。

也可以将密钥直接添加到处理程序 URL 中。例如,将其设置为查询参数:https://example.com/webhook?secret=XXX。

如果您的 Webhook 处理程序访问请求的 HTTP 标头很复杂,这将非常有用。

速率限制

每个 Webhook 每天限制触发 1000 次。您可以在 Webhook 设置页面中的“活动”选项卡中查看您的使用情况。

如果您需要增加 Webhook 的触发次数,请发送邮件至 [email protected] 联系我们。

开发您的 Webhooks

如果您没有 HTTPS 端点/URL,可以尝试使用公共工具进行 Webhook 测试。这些工具充当捕获所有发送给它们的请求的万能工具,并返回 200 OK 状态代码。Beeceptor 是一个可以用来创建临时 HTTP 端点并查看传入有效负载的工具。另一个此类工具是 Webhook.site

此外,您可以在开发过程中将真实的 Webhook 有效负载路由到本地计算机上运行的代码。这是一种在开发期间测试和调试以加快集成的绝佳方式。您可以通过将本地主机端口公开到互联网来实现此目的。要能够走这条路,您可以使用 ngroklocaltunnel

调试 Webhooks

您可以轻松找到 Webhook 最近生成的事件。打开 Webhook 的活动选项卡。在那里,您将看到最近事件的列表。

image.png

在这里,您可以查看生成的事件的 HTTP 状态代码和有效负载。此外,您可以通过单击“重放”按钮来重放这些事件!

注意:更改 Webhook 的目标 URL 或密钥时,重放事件会将有效负载发送到更新的 URL。

常见问题

我可以在我的组织中定义 Webhook,而不是我的用户帐户吗?

目前不支持。

如何订阅所有仓库(或整个仓库类型,例如所有模型)上的事件?

目前尚未向最终用户公开,但如果您发送电子邮件至 [email protected],我们可以为您启用此功能。

< > GitHub 上的更新