Webhooks

Les webhooks constituent un socle pour les fonctionnalités liées au MLOps. Ils vous permettent d’écouter les nouvelles modifications sur des dépôts spécifiques ou sur l’ensemble des dépôts appartenant à des utilisateurs/organisations particuliers que vous souhaitez suivre. Ce guide explique d’abord comment gérer les webhooks de manière programmatique. Nous verrons ensuite comment exploiter huggingface_hub pour créer un serveur à l’écoute des webhooks et le déployer sur un Space.

Ce guide suppose que vous êtes familier avec le concept de webhooks sur le Huggingface Hub. Pour en savoir plus sur les webhooks eux-mêmes, vous devriez d'abord lire ce guide.

Gestion des Webhooks

huggingface_hub vous permet de gérer vos webhooks de manière programmatique. Vous pouvez lister vos webhooks existants, en créer de nouveaux, et les mettre à jour, activer, désactiver ou supprimer. Cette section vous guide à travers les procédures en utilisant les fonctions API du Hugging Face Hub.

Créer un Webhook

Pour créer un nouveau webhook, utilisez create_webhook() et spécifiez l'URL vers laquelle les charges utiles doivent être envoyées, les événements à surveiller, et éventuellement définissez un domaine et un secret pour la sécurité.

from huggingface_hub import create_webhook

# Example: Creating a webhook
webhook = create_webhook(
    url="https://webhook.site/your-custom-url",
    watched=[{"type": "user", "name": "your-username"}, {"type": "org", "name": "your-org-name"}],
    domains=["repo", "discussion"],
    secret="your-secret"
)

Un webhook peut également déclencher l’exécution d’un Job sur l’infrastructure de Hugging face au lieu d’envoyer la charge utile à une URL. Dans ce cas, vous devez transmettre l’ID d’un Job source.

from huggingface_hub import create_webhook

# Example: Creating a webhook that triggers a Job
webhook = create_webhook(
    job_id=job_id,
    watched=[{"type": "user", "name": "your-username"}, {"type": "org", "name": "your-org-name"}],
    domains=["repo", "discussion"],
    secret="your-secret"
)

Le webhook déclenche le Job avec la charge utile du webhook dans la variable d’environnement WEBHOOK_PAYLOAD. Les secrets du Job source ne sont pas copiés vers le webhook. Si le Job déclenché a besoin de secrets (par ex. HF_TOKEN), passez-les avec secrets={"HF_TOKEN": "hf_***"}. Avec update_webhook(), vous devez passer job_id en même temps que secrets. Les secrets listés remplacent les valeurs stockées, une chaîne vide supprime un secret, et tous les autres secrets sont conservés. Pour plus d’informations sur les Hugging Face Jobs, le matériel disponible (CPU, GPU) et les scripts UV, consultez la documentation des Jobs.

Liste des Webhooks

Pour afficher tous les webhooks que vous avez configurés, vous pouvez les lister à l'aide de list_webhooks(). Cela est utile pour vérifier leurs identifiants, URL et statuts.

from huggingface_hub import list_webhooks

# Example: Listing all webhooks
webhooks = list_webhooks()
for webhook in webhooks:
    print(webhook)

Mise à jour d'un Webhook

Si vous devez modifier la configuration d'un webhook existant, par exemple l'URL ou les événements qu'il surveille, vous pouvez le mettre à jour à l'aide de update_webhook().

from huggingface_hub import update_webhook

# Example: Updating a webhook
updated_webhook = update_webhook(
    webhook_id="your-webhook-id",
    url="https://new.webhook.site/url",
    watched=[{"type": "user", "name": "new-username"}],
    domains=["repo"]
)

Activation et désactivation des Webhooks

Vous pouvez vouloir désactiver temporairement un webhook sans le supprimer. Cela est possible à l'aide de disable_webhook(), et le webhook peut être réactivé ultérieurement avec enable_webhook().

from huggingface_hub import enable_webhook, disable_webhook

# Example: Enabling a webhook
enabled_webhook = enable_webhook("your-webhook-id")
print("Enabled:", enabled_webhook)

# Example: Disabling a webhook
disabled_webhook = disable_webhook("your-webhook-id")
print("Disabled:", disabled_webhook)

Supprimer un Webhook

Lorsqu'un webhook n'est plus nécessaire, il peut être supprimé définitivement à l'aide de delete_webhook().

from huggingface_hub import delete_webhook

# Example: Deleting a webhook
delete_webhook("your-webhook-id")

Gérer les Webhooks depuis l’interface en ligne de commande

Toutes les opérations décrites ci-dessus sont également disponibles via l'interface en ligne de commande hf. C'est particulièrement utile pour les scripts et les flux de travail agentiques.

# List all webhooks
>>> hf webhooks ls

# Get details about a specific webhook
>>> hf webhooks info <webhook_id>

# Create a webhook that pings a URL
>>> hf webhooks create --url https://example.com/hook --watch model:bert-base-uncased --domain repo

# Create a webhook that triggers a Job
>>> hf webhooks create --job-id <job_id> --watch user:julien-c

# Create a webhook that triggers a Job with your HF token as a secret
>>> hf webhooks create --job-id <job_id> --watch bucket:my-org/my-bucket --secrets HF_TOKEN

# Update an existing webhook
>>> hf webhooks update <webhook_id> --url https://new-url.com/hook

# Enable / disable a webhook
>>> hf webhooks enable <webhook_id>
>>> hf webhooks disable <webhook_id>

# Delete a webhook (with confirmation prompt)
>>> hf webhooks delete <webhook_id>

L'option --watch utilise le format type:name où type est l'un des éléments suivants : model, dataset, space, org ou user. Elle peut être répétée pour surveiller plusieurs éléments. Pour la liste complète des options, exécutez hf webhooks <command> --help. Pour plus de détails, consultez le guide CLI.

Serveur de Webhooks

La classe de base que nous utiliserons dans cette section du guide est WebhooksServer(). Il s'agit d'une classe permettant de configurer facilement un serveur capable de recevoir des webhooks depuis le Huggingface Hub. Le serveur est basé sur une application Gradio. Il dispose d'une interface utilisateur pour afficher des instructions à votre attention ou à celle de vos utilisateurs, ainsi que d'une API pour écouter les webhooks.

Pour voir un exemple fonctionnel d’un serveur de webhook, consultez celui du Spaces CI Bot. Il s’agit d’un Space qui lance des environnements éphémères lorsqu’une PR est ouverte sur un Space.

Il s'agit d'une fonctionnalité expérimentale. Cela signifie que nous travaillons encore à améliorer l'API. Des modifications cassantes pourraient être introduites à l'avenir sans préavis. Assurez-vous de fixer la version de huggingface_hub dans vos dépendances.

Créer un point de terminaison

Mettre en place un point de terminaison de webhook est aussi simple que de décorer une fonction. Voyons un premier exemple pour expliquer les principaux concepts :

# app.py
from huggingface_hub import webhook_endpoint, WebhookPayload

@webhook_endpoint
async def trigger_training(payload: WebhookPayload) -> None:
    if payload.repo.type == "dataset" and payload.event.action == "update":
        # Trigger a training job if a dataset is updated
        ...

Enregistrez cet extrait dans un fichier nommé 'app.py' et exécutez-le avec 'python app.py'. Vous devriez voir un message de ce type :

Webhook secret is not defined. This means your webhook endpoints will be open to everyone.
To add a secret, set `WEBHOOK_SECRET` as environment variable or pass it at initialization:
        `app = WebhooksServer(webhook_secret='my_secret', ...)`
For more details about webhook secrets, please refer to https://huggingface.co/docs/hub/webhooks#webhook-secret.
Running on local URL:  http://127.0.0.1:7860
Running on public URL: https://1fadb0f52d8bf825fc.gradio.live

This share link expires in 72 hours. For free permanent hosting and GPU upgrades (NEW!), check out Spaces: https://huggingface.co/spaces

Webhooks are correctly setup and ready to use:
  - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training
Go to https://huggingface.co/settings/webhooks to setup your webhooks.

Bien joué ! Vous venez de lancer un serveur de webhook ! Détaillons exactement ce qui s'est passé :

1. En décorant une fonction avec webhook_endpoint(), un objet WebhooksServer() a été créé en arrière-plan. Comme vous pouvez le voir, ce serveur est une application Gradio qui s’exécute sur http://127.0.0.1:7860. Si vous ouvrez cette URL dans votre navigateur, vous verrez une page d’accueil avec des instructions concernant les webhooks enregistrés.
2. Une application Gradio est, sous le capot, un serveur FastAPI. Une nouvelle route POST /webhooks/trigger_training y a été ajoutée. C'est cette route qui écoutera les webhooks et exécutera la fonction trigger_training lorsqu'elle est déclenchée. FastAPI analysera automatiquement la charge utile et la transmettra à la fonction sous forme d'objet WebhookPayload. Il s'agit d'un objet pydantic qui contient toutes les informations relatives à l'événement ayant déclenché le webhook.
3. L’application Gradio a également ouvert un tunnel pour recevoir des requêtes depuis Internet. C’est la partie intéressante : vous pouvez configurer un Webhook sur https://huggingface.co/settings/webhooks pointant vers votre machine locale. C’est utile pour déboguer votre serveur de webhook et itérer rapidement avant de le déployer sur un Space.
4. Enfin, les journaux vous indiquent également que votre serveur n'est actuellement pas sécurisé par un secret. Ce n'est pas problématique pour le débogage local, mais c'est un point à garder en tête pour la suite.

Par défaut, le serveur est démarré à la fin de votre script. Si vous l’exécutez dans un notebook, vous pouvez démarrer le serveur manuellement en appelant decorated_function.launch(). Étant donné qu’un serveur unique est utilisé, vous n’avez à démarrer le serveur qu’une seule fois, même si vous avez plusieurs points de terminaison.

Configurer un Webhook

Maintenant que votre serveur webhook est en cours d’exécution, vous souhaitez configurer un Webhook afin de commencer à recevoir des messages. Accédez à https://huggingface.co/settings/webhooks, cliquez sur « Add a new webhook » et configurez votre Webhook. Définissez les dépôts cibles que vous souhaitez surveiller ainsi que l’URL du Webhook, ici https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training.

Et c’est tout ! Vous pouvez maintenant déclencher ce webhook en mettant à jour le dépôt cible (par exemple, en poussant un commit). Consultez l’onglet Activité de votre Webhook pour voir les événements qui ont été déclenchés. Maintenant que vous avez une configuration fonctionnelle, vous pouvez la tester et itérer rapidement. Si vous modifiez votre code et redémarrez le serveur, votre URL publique peut changer. Assurez-vous de mettre à jour la configuration du webhook sur le Hub si nécessaire.

Déployer sur un Space

Maintenant que vous disposez d'un serveur webhook fonctionnel, l'objectif est de le déployer sur un Space. Rendez-vous sur https://huggingface.co/new-space pour créer un Space. Donnez-lui un nom, sélectionnez le SDK Gradio et cliquez sur « Create Space ». Téléchargez votre code sur le Space dans un fichier nommé app.py. Votre Space démarrera automatiquement ! Pour plus de détails sur les Spaces, veuillez consulter ce guide.

Votre serveur webhook est maintenant en cours d’exécution sur un Space public. Dans la plupart des cas, vous voudrez le sécuriser avec un secret. Accédez aux paramètres de votre Space > Section « Repository secrets » > « Add a secret ». Définissez la variable d’environnement WEBHOOK_SECRET avec la valeur de votre choix. Retournez aux paramètres Webhooks et définissez le secret dans la configuration du webhook. Désormais, seules les requêtes avec le secret correct seront acceptées par votre serveur.

Et c’est tout ! Votre Space est maintenant prêt à recevoir des webhooks du Hub. Veuillez garder à l’esprit que si vous exécutez le Space sur un matériel gratuit « cpu-basic », il sera arrêté après 48 heures d’inactivité. Si vous avez besoin d’un Space permanent, vous devriez envisager de passer à un matériel amélioré.

Utilisation avancée

Le guide ci-dessus a expliqué la méthode la plus rapide pour configurer un WebhooksServer(). Dans cette section, nous allons voir comment le personnaliser davantage.

Plusieurs points de terminaison

Vous pouvez enregistrer plusieurs points de terminaison sur le même serveur. Par exemple, vous pouvez vouloir disposer d'un point de terminaison pour déclencher un travail d'entraînement et d'un autre pour déclencher une évaluation de modèle. Vous pouvez le faire en ajoutant plusieurs décorateurs @webhook_endpoint :

# app.py
from huggingface_hub import webhook_endpoint, WebhookPayload

@webhook_endpoint
async def trigger_training(payload: WebhookPayload) -> None:
    if payload.repo.type == "dataset" and payload.event.action == "update":
        # Trigger a training job if a dataset is updated
        ...

@webhook_endpoint
async def trigger_evaluation(payload: WebhookPayload) -> None:
    if payload.repo.type == "model" and payload.event.action == "update":
        # Trigger an evaluation job if a model is updated
        ...

Ce qui créera deux points de terminaison :

(...)
Webhooks are correctly setup and ready to use:
  - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training
  - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_evaluation

Serveur personnalisé

Pour plus de flexibilité, vous pouvez également créer directement un objet WebhooksServer(). C'est utile si vous souhaitez personnaliser la page d'accueil de votre serveur. Vous pouvez le faire en passant une Gradio UI qui remplacera celle par défaut. Par exemple, vous pouvez ajouter des instructions pour vos utilisateurs ou ajouter un formulaire pour déclencher manuellement les webhooks. Lors de la création d'un WebhooksServer(), vous pouvez enregistrer de nouveaux webhooks à l'aide du décorateur add_webhook().

Voici un exemple complet :

import gradio as gr
from fastapi import Request
from huggingface_hub import WebhooksServer, WebhookPayload

# 1. Define  UI
with gr.Blocks() as ui:
    ...

# 2. Create WebhooksServer with custom UI and secret
app = WebhooksServer(ui=ui, webhook_secret="my_secret_key")

# 3. Register webhook with explicit name
@app.add_webhook("/say_hello")
async def hello(payload: WebhookPayload):
    return {"message": "hello"}

# 4. Register webhook with implicit name
@app.add_webhook
async def goodbye(payload: WebhookPayload):
    return {"message": "goodbye"}

# 5. Start server (optional)
app.launch()

1. Nous définissons une interface utilisateur personnalisée à l'aide de blocs Gradio. Cette interface sera affichée sur la page d'accueil du serveur.
2. Nous créons un objet WebhooksServer() avec une interface utilisateur personnalisée et un secret. Le secret est facultatif et peut être défini avec la variable d'environnement WEBHOOK_SECRET.
3. Nous enregistrons un webhook avec un nom explicite. Cela créera un point de terminaison à /webhooks/say_hello.
4. Nous enregistrons un webhook avec un nom implicite. Cela créera un point de terminaison à /webhooks/goodbye.
5. Nous démarrons le serveur. Cette étape est facultative, car votre serveur sera automatiquement démarré à la fin du script.