跳到主要内容

Webhooks

提示

Webhook 现已对所有用户开放！

Webhook 是 MLOps 相关功能的基础。你可以监听特定仓库，或某个用户/组织全部仓库（不仅限于你自己的仓库）的最新变更。

借助它们可以自动转换模型、构建社区机器人、为模型/数据集/Spaces 构建 CI/CD 等等。

以下为 Webhook 的使用文档；你也可以查看一些示例指南，了解 Webhook 的典型用法：

创建 Webhook​

你可以在 Webhook 设置 页面创建或编辑 Webhook：

Settings of an individual webhook

Webhook 可监听仓库更新、拉取请求、讨论以及新评论。甚至可以创建一个 Space 来响应 Webhook！

Webhook 负载（Payload）​

注册 Webhook 后，新的事件会以 HTTP POST 请求发送到你指定的目标 URL，负载为 JSON 编码。

你可以在 Webhook 设置页面的 activity 标签查看发送历史，并可重放（replay）历史事件，便于调试：

image.png

以下为打开拉取请求时发送的完整 payload：

{
  "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 始终存在，用于描述事件类型。

它包含两个子属性：event.action 与 event.scope。

event.scope 可能的取值包括：

  • "repo"：仓库级事件。对应的 action 可能是："create"、"delete"、"update"、"move"。
  • "repo.content"：仓库内容事件，例如新提交或标签。由于新建引用/提交，该范围也会在新 PR 时触发。对应 action 恒为 "update"。
  • "repo.config"：仓库配置事件，例如更新 Space 密钥、设置、DOI、启用/禁用等。对应 action 恒为 "update"。
  • "discussion"：创建讨论或 PR、更新标题或状态、合并等。对应 action 可能是："create"、"delete"、"update"。
  • "discussion.comment"：创建、更新或隐藏评论。对应 action 可能是："create"、"update"。

未来可能新增更多 scope。为了兼容未知事件，你的 Webhook 处理逻辑可以将更细粒度 scope 的任意操作视为上一级 scope 的 "update"。

例如，若未来新增 "repo.config.dois"，你的 handler 可以将其视为 "repo.config" scope 的 "update" 操作。

Repo​

当前版本中，顶层属性 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 分支的最新提交哈希。仅当 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。你可以据此对特定 PR 的新提交、标签或分支做出响应。

配置变更​

当 event.scope 为 "repo.config" 时，会包含 updatedConfig 属性，其为包含更新配置的对象。例如：

"updatedConfig": {
  "private": false
}

或：

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

若配置键暂不被 Webhook 支持，则返回：

"updatedConfig": {}

目前仅支持 private 与 xetEnabled。若你需要更多键，请发邮件至 [email protected] 告知我们。

讨论与拉取请求​

在社区事件（讨论与 PR）中，顶层属性 discussion 会出现。discussion.isPullRequest 是布尔值，用于指示该讨论是否为 PR（在 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 handler 的 payload 确实来自 Hugging Face。

如果设置了密钥，我们会在每次请求中以 X-Webhook-Secret HTTP 头发送该密钥。仅支持 ASCII 字符。

提示

也可以将密钥直接写在 handler URL 中，例如作为查询参数：https://example.com/webhook?secret=XXX。

当你的 Webhook handler 难以读取 HTTP 头时，这种方式会很有帮助。

速率限制​

每个 Webhook 每 24 小时最多触发 1,000 次。你可以在 Webhook 设置页面的 “Activity” 标签查看使用情况。

若需提高触发次数，请升级到 PRO、Team 或 Enterprise 并联系 [email protected]。

开发 Webhook​

如果没有 HTTPS 端点/URL，可以使用公开的 Webhook 测试工具。这些工具会捕获所有发送到它们的请求，并返回 200 OK。例如 Beeceptor 可以创建临时 HTTP 端点并查看 payload，Webhook.site 也是常用工具。

你也可以在开发时将真实 Webhook payload 路由到本地代码进行测试。这是调试与快速集成的好方法，你可以通过，将本地端口暴露到公网来实现，例如使用 ngrok 或 localtunnel。

调试 Webhook​

你可以轻松查看 Webhook 最近生成的事件。在 Webhook 的 activity 标签中，会列出所有最近事件。

image.png

在此可以查看事件的 HTTP 状态码与 payload，还可以点击 Replay 按钮重放事件！

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

常见问题​

我可以在组织级别或个人账户级别分别定义 Webhook 吗？​

暂不支持。

如何订阅 HF 上所有事件（或某一类仓库，如全部模型）？​

目前暂不向终端用户开放，如有需要，请发送邮件至 [email protected]，我们可以为你开启。

最后于 更新