Model Database's logo

Hub Python Library documentation

Webhooks Server

Model Database's logo
Join the Model Database community

and get access to the augmented documentation experience

to get started

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

< >

( *args **kwargs )

Parameters

  • ui (gradio.Blocks, optional) — A Gradio UI instance to be used as the Space landing page. If None, 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 the WEBHOOK_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).

Example:

import gradio as gr
from huggingface_hub import WebhooksServer, WebhookPayload

with gr.Blocks() as ui:
    ...

app = WebhooksServer(ui=ui, webhook_secret="my_secret_key")

@app.add_webhook("/say_hello")
async def hello(payload: WebhookPayload):
    return {"message": "hello"}

app.run()

@webhook_endpoint

huggingface_hub.webhook_endpoint

< >

( path: typing.Optional[str] = None )

Parameters

  • path (str, optional) — The URL path to register the webhook function. If not provided, the function name will be used as the path. In any case, all webhooks are registered under /webhooks.

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

< >

( 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

< >

( 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

< >

( id: str author: ObjectId hidden: bool content: typing.Optional[str] = None url: WebhookPayloadUrl )

WebhookPayloadDiscussion

class huggingface_hub.WebhookPayloadDiscussion

< >

( 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

< >

( base: str mergeCommitId: typing.Optional[str] = None )

WebhookPayloadEvent

class huggingface_hub.WebhookPayloadEvent

< >

( action: typing.Literal['create', 'delete', 'move', 'update'] scope: str )

WebhookPayloadMovedTo

class huggingface_hub.WebhookPayloadMovedTo

< >

( name: str owner: ObjectId )

WebhookPayloadRepo

class huggingface_hub.WebhookPayloadRepo

< >

( 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 )

WebhookPayloadUrl

class huggingface_hub.WebhookPayloadUrl

< >

( web: str api: typing.Optional[str] = None )

WebhookPayloadWebhook

class huggingface_hub.WebhookPayloadWebhook

< >

( id: str version: typing.Literal[3] )

←TensorBoard logger