Hugging Face's logo

Hub 文档

Webhooks

Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始使用

Webhooks

Webhooks 现已公开可用！

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

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

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

创建你的 Webhook

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

Settings of an individual webhook

Webhooks 可以监视仓库更新、拉取请求、讨论和新评论。甚至可以创建一个 Space 来响应你的 Webhooks！

Webhook Payload

注册 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.action 和 event.scope。

event.scope 将是以下值之一

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

未来可能会添加更多 scope。为了处理未知事件，您的 webhook 处理程序可以将任何对缩小 scope 的操作视为对更广泛 scope 的 "update" 操作。

例如，如果未来添加了 "repo.config.dois" scope，则您的 webhook 处理程序可以将具有该 scope 的任何事件视为对 "repo.config" scope 的 "update" 操作。

仓库

在当前版本的 webhook 中，顶层属性 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。

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

配置更改

当顶层属性 event.scope 为 "repo.config" 时，将指定 updatedConfig 属性。它是一个包含已更新配置的对象。以下是示例值

"updatedConfig": {
  "private": false
}

或

"updatedConfig": {
  "xetEnabled": true,
}

或者，当 webhook 不支持更新的配置键时

"updatedConfig": {}

目前仅支持 private 和 xetEnabled。如果您希望此处提供更多配置键，请通过 website@huggingface.co 告知我们。

讨论和拉取请求

顶层属性 discussion 在社区事件（讨论和拉取请求）上指定。 discussion.isPullRequest 属性是一个布尔值，指示讨论是否也是拉取请求（在 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。

如果访问请求的 HTTP 标头对于您的 Webhook 处理程序来说很复杂，这将很有帮助。

速率限制

每个 Webhook 每天最多触发 1,000 次。您可以在 Webhook 设置页面的“活动”选项卡中查看您的使用情况。

如果您需要增加 Webhook 的触发次数，请通过 website@huggingface.co 联系我们。

开发您的 Webhook

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

此外，您可以在开发期间将真实的 Webhook payload 路由到本地机器上运行的代码。这是测试和调试以实现更快集成的好方法。您可以通过将本地主机端口暴露给互联网来做到这一点。为了能够走这条路，您可以使用 ngrok 或 localtunnel。

调试 Webhook

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

image.png

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

注意：当更改 Webhook 的目标 URL 或密钥时，重放事件会将 payload 发送到更新后的 URL。

常见问题解答

我可以在我的组织而不是我的用户帐户上定义 webhook 吗？

不，目前不支持。

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

目前不对最终用户开放，但如果您发送电子邮件至 website@huggingface.co，我们可以为您切换此功能。

< > 在 GitHub 上更新

←Collections 操作指南：使用 Auto-Train 自动微调→