Skip to content

Commit 82f0d1e

Browse files
coyotte508julien-cSBrandeispatrickvonplatensanchit-gandhi
authored
📝 Document webhooks (#554)
Co-authored-by: Julien Chaumond <[email protected]> Co-authored-by: Simon Brandeis <[email protected]> Co-authored-by: Patrick von Platen <[email protected]> Co-authored-by: Sanchit Gandhi <[email protected]> Co-authored-by: Omar Sanseviero <[email protected]> Co-authored-by: Victor Muštar <[email protected]>
1 parent 41758b1 commit 82f0d1e

File tree

2 files changed

+197
-0
lines changed

2 files changed

+197
-0
lines changed

‎docs/hub/_toctree.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@
1212
title: Pull Requests & Discussions
1313
- local: notifications
1414
title: Notifications
15+
- local: webhooks
16+
title: Webhooks
1517
- local: repositories-next-steps
1618
title: Next Steps
1719
- local: repositories-licenses

‎docs/hub/webhooks.md‎

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
# Webhooks
2+
3+
**Join the [webhooks-explorers](https://huggingface.co/webhooks-explorers) organization to beta-test webhooks!**
4+
5+
Webhooks are a foundation for MLOps related features. You can use them to auto-convert models, build community bots, or build CI/CD for your models, datasets, and Spaces.
6+
7+
They allow you to listen for new changes on specific repos or repos belonging to particular users/organizations (not just your repos, but any repo!).
8+
9+
You can create new webhooks and edit exiting ones in your webhooks [settings](https://huggingface.co/settings/webhooks):
10+
11+
![Settings of an individual webhook](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/webhook-settings.png)
12+
13+
Webhooks can watch for repos updates, Pull requests, discussions, and new comments. It's even possible to create a Space to react to your webhooks!
14+
15+
<!-- Todo: add a link to a guide with a real example -->
16+
17+
## Webhook Payloads
18+
19+
After registering a webhook, you will be notified of new events via an `HTTP POST` call on the specified target URL. The payload is encoded in JSON.
20+
21+
You can view the history of payloads sent in the activity tab of the webhook settings page, it's also possible to replay past webhooks for easier debugging:
22+
23+
24+
![image.png](https://s3.amazonaws.com/moonup/production/uploads/1671034300077-61d2f90c3c2083e1c08af22d.png)
25+
26+
As an example, here is the full payload when a Pull request is opened:
27+
28+
```json
29+
{
30+
"event": {
31+
"action": "create",
32+
"scope": "discussion"
33+
},
34+
"repo": {
35+
"type": "model",
36+
"name": "gpt2",
37+
"id": "621ffdc036468d709f17434d",
38+
"private": false,
39+
"url": {
40+
"web": "https://hugginface.co/gpt2",
41+
"api": "https://hugginface.co/api/models/gpt2"
42+
},
43+
"owner": {
44+
"id": "628b753283ef59b5be89e937"
45+
}
46+
},
47+
"discussion": {
48+
"id": "6399f58518721fdd27fc9ca9",
49+
"title": "Update co2 emissions",
50+
"url": {
51+
"web": "https://hugginface.co/gpt2/discussions/19",
52+
"api": "https://hugginface.co/api/models/gpt2/discussions/19"
53+
},
54+
"status": "open",
55+
"author": {
56+
"id": "61d2f90c3c2083e1c08af22d"
57+
},
58+
"num": 19,
59+
"isPullRequest": true,
60+
"changes": {
61+
"base": "refs/heads/main"
62+
}
63+
},
64+
"comment": {
65+
"id": "6399f58518721fdd27fc9caa",
66+
"author": {
67+
"id": "61d2f90c3c2083e1c08af22d"
68+
},
69+
"content": "Add co2 emissions information to the model card",
70+
"hidden": false,
71+
"url": {
72+
"web": "https://hugginface.co/gpt2/discussions/19#6399f58518721fdd27fc9caa"
73+
}
74+
},
75+
"webhook": {
76+
"id": "6390e855e30d9209411de93b",
77+
"version": 3
78+
}
79+
}
80+
```
81+
82+
### Event
83+
84+
The top-level properties `event` is always specified and used to determine the nature of the event.
85+
86+
It has two sub-properties: `event.action` and `event.scope`.
87+
88+
`event.scope` will be one of the following values:
89+
90+
- `"repo"` - Global events on repos. Possible values for the associated `action`: `"create"`, `"delete"`, `"update"`, `"move"`.
91+
- `"repo.content"` - Events on the repo's content, such as new commits or tags. It triggers on new Pull requests as well due to the newly created reference/commit. The associated `action` is always `"update"`.
92+
- `"repo.config"` - Events on the config: update Space secrets, update settings, update DOIs, disabled or not, etc. The associated `action` is always `"update"`.
93+
- `"discussion"` - Creating a discussion or Pull request, updating the title or status, and merging. Possible values for the associated `action`: `"create"`, `"delete"`, `"update"`.
94+
- `"discussion.comment"` - Creating, updating, and hiding a comment. Possible values for the associated `action`: `"create"`, `"update"`.
95+
96+
More scopes can be added in the future. To handle unknown events, your webhook handler can consider any action on a narrowed scope to be an `"update"` action on the broader scope.
97+
98+
For example, if the `"repo.config.dois"` scope is added in the future, any event with that scope can be considered by your webhook handler as an `"update"` action on the `"repo.config"` scope.
99+
100+
### Repo
101+
102+
In the current version of webhooks, the top level property `repo` is always specified, as events can always be associated to a repo. For example, consider the following value:
103+
104+
```json
105+
"repo": {
106+
"type": "model",
107+
"name": "some-user/some-repo",
108+
"id": "6366c000a2abcdf2fd69a080",
109+
"private": false,
110+
"url": {
111+
"web": "http://huggingface.co/some-user/some-repo",
112+
"api": "http://huggingface.co/api/models/some-user/some-repo"
113+
},
114+
"headSha": "c379e821c9c95d613899e8c4343e4bfee2b0c600",
115+
"tags": [
116+
"license:other",
117+
"has_space"
118+
],
119+
"owner": {
120+
"id": "61d2000c3c2083e1c08af22d"
121+
}
122+
}
123+
```
124+
125+
`repo.headSha` is the sha of the latest commit on the repo's `main` branch. It is only sent when `event.scope` starts with `"repo"`, not on community events like discussions and comments.
126+
127+
### Discussion and Pull Requests
128+
129+
The top-level property `discussion` is specified on community events (discussions and Pull requests). The `discussion.isPullRequest` property is a boolean indicating if the discussion is also a Pull request (on the Hub, a PR is a special type of discussion). Here is an example value:
130+
131+
```json
132+
"discussion": {
133+
"id": "639885d811ae2bad2b7ba461",
134+
"title": "Hello!",
135+
"url": {
136+
"web": "https://huggingface.co/some-user/some-repo/discussions/3",
137+
"api": "https://huggingface.co/api/models/some-user/some-repo/discussions/3"
138+
},
139+
"status": "open",
140+
"author": {
141+
"id": "61d2000c3c2083e1c08af22d"
142+
},
143+
"isPullRequest": true,
144+
"changes": {
145+
"base": "refs/heads/main"
146+
}
147+
"num": 3
148+
}
149+
```
150+
151+
### Comment
152+
153+
The top level property `comment` is specified when a comment is created (including on discussion creation) or updated. Here is an example value:
154+
155+
```json
156+
"comment": {
157+
"id": "6398872887bfcfb93a306f18",
158+
"author": {
159+
"id": "61d2000c3c2083e1c08af22d"
160+
},
161+
"content": "This adds an env key",
162+
"hidden": false,
163+
"url": {
164+
"web": "http://huggingface.co/some-user/some-repo/discussions/4#6398872887bfcfb93a306f18"
165+
}
166+
}
167+
```
168+
169+
## Webhook secret
170+
171+
Setting a webhook secret is useful to make sure payloads sent to your webhook handler URL are from Hugging Face.
172+
173+
If you set a secret for your webhook, it will be sent along as an `X-Webhook-Secret` HTTP header on every request. Only ASCII characters are supported.
174+
175+
<Tip>
176+
It's also possible to add the secret directly in the handler URL. For example, setting it as a query parameter: https://example.com/webhook?secret=XXX.
177+
178+
This can be helpful if accessing the HTTP headers of the request is complicated for your webhook handler.
179+
</Tip>
180+
181+
## Rate limiting
182+
183+
Each webhook is limited to 1,000 triggers per 24 hours. You can view your usage in the Webhook settings page in the "Activity" tab.
184+
185+
If you need to increase the number of triggers for your webhook, contact us at [email protected].
186+
187+
## Debugging webhooks
188+
189+
Go in the activity tab for your webhook, there you will see the list of recent events.
190+
191+
![image.png](https://s3.amazonaws.com/moonup/production/uploads/1671035382840-61d2f90c3c2083e1c08af22d.png)
192+
193+
You will see the HTTP status code and the payload of past events. You can replay those events by clicking on the `replay` button!
194+
195+
When changing the target URL or secret of a webhook, replaying an event will send the payload to the updated URL.

0 commit comments

Comments
 (0)