Skip to content

Document the Webhook-Id delivery header #2749

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Kakulukian wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Document the Webhook-Id delivery header #2749

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
710f3db
Document the Webhook-Id delivery header
Aug 31, 2026
459ad64
wh retry
Kakulukian Aug 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/hub/jobs-webhooks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ The webhook triggers the Job with the following environment variables:
- `WEBHOOK_REPO_ID`: the repository name (e.g., `user/repo-name`)
- `WEBHOOK_REPO_TYPE`: the repository type (`model`, `dataset`, or `space`)
- `WEBHOOK_SECRET`: the webhook secret, if one was configured
- `WEBHOOK_ID`: a unique identifier for the delivery, stable across retries of that delivery

The webhook payload contains multiple fields, here are a few useful ones:

Expand Down
4 changes: 4 additions & 0 deletions docs/hub/webhooks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -274,6 +274,8 @@ If you set a secret for your Webhook, it will be sent along as an `X-Webhook-Sec

Webhook payloads are delivered asynchronously, shortly after the event happens on the Hub. Order is not guaranteed: if several events occur close together, they may arrive out of sequence.

Each delivery has a unique `Webhook-Id` HTTP header. Retries of a failed delivery reuse the same ID, so you can treat it as an idempotency key and process each event once.

When deliveries to a Webhook keep failing, the Webhook is automatically suspended and its owner is notified by email. You can troubleshoot it and re-enable it from your Webhooks [settings](https://huggingface.co/settings/webhooks).

## Rate limiting
Expand All @@ -298,6 +300,8 @@ Here you can review the HTTP status code and the payload of the generated events

Note: When changing the target URL or secret of a Webhook, replaying an event will send the payload to the updated URL.

Note: A replayed event is sent with the same `Webhook-Id` as the original delivery.

## FAQ

##### Can I define webhooks on my organization vs my user account?
Expand Down
Loading