Webhooks Server
Webhooks are a foundation for MLOps-related features. They allow you to listen for new changes on specific repos or to all repos belonging to particular users/organizations you’re interested in following. To learn more about webhooks on the Huggingface Hub, you can read the Webhooks guide.
Check out this guide for a step-by-step tutorial on how to setup your webhooks server and deploy it as a Space.
This is an experimental feature. This means that we are still working on improving the API. Breaking changes might be
introduced in the future without prior notice. Make sure to pin the version of huggingface_hub
in your requirements.
A warning is triggered when you use an experimental feature. You can disable it by setting HF_HUB_DISABLE_EXPERIMENTAL_WARNING=1
as an environment variable.
Server
The server is a Gradio app. It has a UI to display instructions for you or your users and an API to listen to webhooks. Implementing a webhook endpoint is as simple as decorating a function. You can then debug it by redirecting the Webhooks to your machine (using a Gradio tunnel) before deploying it to a Space.
WebhooksServer
huggingface_hub.WebhooksServer
< source >( ui: typing.Optional[gradio.blocks.Blocks] = None webhook_secret: typing.Optional[str] = None )
Parameters
-
ui (
gradio.Blocks
, optional) — A Gradio UI instance to be used as the Space landing page. IfNone
, a UI displaying instructions about the configured webhooks is created. -
webhook_secret (
str
, optional) — A secret key to verify incoming webhook requests. You can set this value to any secret you want as long as you also configure it in your webhooks settings panel. You can also set this value as theWEBHOOK_SECRET
environment variable. If no secret is provided, the webhook endpoints are opened without any security.
The WebhooksServer() class lets you create an instance of a Gradio app that can receive Huggingface webhooks.
These webhooks can be registered using the add_webhook()
decorator. Webhook endpoints are added to
the app as a POST endpoint to the FastAPI router. Once all the webhooks are registered, the run
method has to be
called to start the app.
It is recommended to accept WebhookPayload as the first argument of the webhook function. It is a Pydantic model that contains all the information about the webhook event. The data will be parsed automatically for you.
Check out the webhooks guide for a step-by-step tutorial on how to setup your WebhooksServer and deploy it on a Space.
WebhooksServer
is experimental. Its API is subject to change in the future.
You must have gradio
installed to use WebhooksServer
(pip install --upgrade gradio
).
@webhook_endpoint
huggingface_hub.webhook_endpoint
< source >( path: typing.Optional[str] = None )
Decorator to start a WebhooksServer() and register the decorated function as a webhook endpoint.
This is a helper to get started quickly. If you need more flexibility (custom landing page or webhook secret), you can use WebhooksServer() directly. You can register multiple webhook endpoints (to the same server) by using this decorator multiple times.
Check out the webhooks guide for a step-by-step tutorial on how to setup your server and deploy it on a Space.
webhook_endpoint
is experimental. Its API is subject to change in the future.
You must have gradio
installed to use webhook_endpoint
(pip install --upgrade gradio
).
Examples: The default usage is to register a function as a webhook endpoint. The function name will be used as the path. The server will be started automatically at exit (i.e. at the end of the script).
from huggingface_hub import webhook_endpoint, WebhookPayload
@webhook_endpoint
async def trigger_training(payload: WebhookPayload):
if payload.repo.type == "dataset" and payload.event.action == "update":
# Trigger a training job if a dataset is updated
...
# Server is automatically started at the end of the script.
Advanced usage: register a function as a webhook endpoint and start the server manually. This is useful if you are running it in a notebook.
from huggingface_hub import webhook_endpoint, WebhookPayload
@webhook_endpoint
async def trigger_training(payload: WebhookPayload):
if payload.repo.type == "dataset" and payload.event.action == "update":
# Trigger a training job if a dataset is updated
...
# Start the server manually
trigger_training.run()
Payload
WebhookPayload is the main data structure that contains the payload from Webhooks. This is
a pydantic
class which makes it very easy to use with FastAPI. If you pass it as a parameter to a webhook endpoint, it
will be automatically validated and parsed as a Python object.
For more information about webhooks payload, you can refer to the Webhooks Payload guide.
class huggingface_hub.WebhookPayload
< source >( event: WebhookPayloadEvent repo: WebhookPayloadRepo discussion: typing.Optional[huggingface_hub._webhooks_payload.WebhookPayloadDiscussion] = None comment: typing.Optional[huggingface_hub._webhooks_payload.WebhookPayloadComment] = None webhook: WebhookPayloadWebhook movedTo: typing.Optional[huggingface_hub._webhooks_payload.WebhookPayloadMovedTo] = None )
WebhookPayload
class huggingface_hub.WebhookPayload
< source >( event: WebhookPayloadEvent repo: WebhookPayloadRepo discussion: typing.Optional[huggingface_hub._webhooks_payload.WebhookPayloadDiscussion] = None comment: typing.Optional[huggingface_hub._webhooks_payload.WebhookPayloadComment] = None webhook: WebhookPayloadWebhook movedTo: typing.Optional[huggingface_hub._webhooks_payload.WebhookPayloadMovedTo] = None )
WebhookPayloadComment
class huggingface_hub.WebhookPayloadComment
< source >( id: str author: ObjectId hidden: bool content: typing.Optional[str] = None url: WebhookPayloadUrl )
WebhookPayloadDiscussion
class huggingface_hub.WebhookPayloadDiscussion
< source >( id: str num: int author: ObjectId url: WebhookPayloadUrl title: str isPullRequest: bool status: typing.Literal['closed', 'draft', 'open', 'merged'] changes: typing.Optional[huggingface_hub._webhooks_payload.WebhookPayloadDiscussionChanges] = None pinned: typing.Optional[bool] = None )
WebhookPayloadDiscussionChanges
class huggingface_hub.WebhookPayloadDiscussionChanges
< source >( base: str mergeCommitId: typing.Optional[str] = None )
WebhookPayloadEvent
class huggingface_hub.WebhookPayloadEvent
< source >( action: typing.Literal['create', 'delete', 'move', 'update'] scope: str )
WebhookPayloadMovedTo
WebhookPayloadRepo
class huggingface_hub.WebhookPayloadRepo
< source >( id: str owner: ObjectId head_sha: typing.Optional[str] = None name: str private: bool subdomain: typing.Optional[str] = None tags: typing.Optional[typing.List[str]] = None type: typing.Literal['dataset', 'model', 'space'] url: WebhookPayloadUrl )