From 710f3dbac3c16d16a2a27586633c97897dc0bb85 Mon Sep 17 00:00:00 2001 From: huggingface-doc-bot Date: Mon, 31 Aug 2026 13:20:05 +0000 Subject: [PATCH 1/2] Document the Webhook-Id delivery header Webhook deliveries now include a `Webhook-Id` HTTP header (and a `WEBHOOK_ID` env var for Job webhooks) that is stable across retries of a delivery, so consumers can dedupe and process events idempotently. Also note that replays reuse the original delivery's id. Co-Authored-By: Claude Opus 5 (1M context) --- docs/hub/jobs-webhooks.md | 1 + docs/hub/webhooks.md | 4 ++++ 2 files changed, 5 insertions(+) diff --git a/docs/hub/jobs-webhooks.md b/docs/hub/jobs-webhooks.md index a1bdf31f90..04dc474b66 100644 --- a/docs/hub/jobs-webhooks.md +++ b/docs/hub/jobs-webhooks.md @@ -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: diff --git a/docs/hub/webhooks.md b/docs/hub/webhooks.md index 9e96a2c862..109725450a 100644 --- a/docs/hub/webhooks.md +++ b/docs/hub/webhooks.md @@ -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. +Every delivery carries a unique identifier in the `Webhook-Id` HTTP header, following the [Standard Webhooks](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md#webhook-headers-sending-metadata-to-consumers) specification. If a delivery fails to reach your endpoint and is retried, every retry reuses the same `Webhook-Id`, so you can use it as an idempotency key to process each event only 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 @@ -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, so a handler that dedupes on that header will skip the replay as a duplicate. + ## FAQ ##### Can I define webhooks on my organization vs my user account? From 459ad64e927e0e3f7a8a81fdeb86387031534e4f Mon Sep 17 00:00:00 2001 From: Sylvestre Date: Mon, 31 Aug 2026 15:29:03 +0200 Subject: [PATCH 2/2] wh retry --- docs/hub/webhooks.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/hub/webhooks.md b/docs/hub/webhooks.md index 109725450a..fa4d596f9c 100644 --- a/docs/hub/webhooks.md +++ b/docs/hub/webhooks.md @@ -274,7 +274,7 @@ 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. -Every delivery carries a unique identifier in the `Webhook-Id` HTTP header, following the [Standard Webhooks](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md#webhook-headers-sending-metadata-to-consumers) specification. If a delivery fails to reach your endpoint and is retried, every retry reuses the same `Webhook-Id`, so you can use it as an idempotency key to process each event only once. +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). @@ -300,7 +300,7 @@ 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, so a handler that dedupes on that header will skip the replay as a duplicate. +Note: A replayed event is sent with the same `Webhook-Id` as the original delivery. ## FAQ