Webhooks

Webhooks 现已公开可用！

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

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

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

创建您的 Webhook

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

Settings of an individual webhook

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

Webhook 有效负载

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

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

{
  "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.action 和 event.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 的触发次数，请发送邮件至 website@huggingface.co 联系我们。

开发您的 Webhooks

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

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

调试 Webhooks

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

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

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

常见问题

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

目前不支持。

如何订阅所有仓库（或整个仓库类型，例如所有模型）上的事件？

目前尚未向最终用户公开，但如果您发送电子邮件至 website@huggingface.co，我们可以为您启用此功能。

< > GitHub 上的更新