Webhooks

Los webhooks son la base de las funciones relacionadas con MLOps. Permiten escuchar nuevos cambios en repositorios específicos o en todos los repositorios de usuarios u organizaciones concretos que desees seguir. Esta guía explica primero cómo gestionar webhooks de forma programática. A continuación, veremos cómo aprovechar huggingface_hub para crear un servidor que escuche webhooks y desplegarlo en un Space.

Esta guía asume que estás familiarizado con el concepto de webhooks en Huggingface Hub. Para obtener más información sobre los webhooks en sí, debes leer primero esta guía.

Gestión de Webhooks

huggingface_hub te permite gestionar tus webhooks de forma programática. Puedes listar tus webhooks existentes, crear nuevos y actualizarlos, habilitarlos, deshabilitarlos o eliminarlos. Esta sección te guía a través de los procedimientos utilizando las funciones de la API de Hugging Face Hub.

Creación de un Webhook

Para crear un nuevo webhook, use create_webhook() y especifique la URL a la que deben enviarse los payloads, qué eventos deben vigilarse y, opcionalmente, establezca un dominio y un secreto para la seguridad.

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 también puede activar la ejecución de un Job en la infraestructura de Hugging face en lugar de enviar el payload a una URL. En este caso, es necesario pasar el ID de un Job de origen.

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

El webhook activa el Job con la carga del webhook en la variable de entorno WEBHOOK_PAYLOAD. Los secretos del Job de origen no se copian al webhook. Si el Job activado necesita secretos (p. ej. HF_TOKEN), pásalos con secrets={"HF_TOKEN": "hf_***"}. Con update_webhook(), debes pasar job_id junto con secrets. Los secretos enumerados reemplazan los valores almacenados, una cadena vacía elimina un secreto y todos los demás secretos se conservan. Para obtener más información sobre Hugging Face Jobs, el hardware disponible (CPU, GPU) y los scripts de UV, consulta la documentación de Jobs.

Listar Webhooks

Para ver todos los webhooks que has configurado, puedes listarlos con list_webhooks(). Esto es útil para revisar sus IDs, URLs y estados.

from huggingface_hub import list_webhooks

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

Actualización de un Webhook

Si necesitas cambiar la configuración de un webhook existente, como la URL o los eventos que observa, puedes actualizarlo usando 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"]
)

Activar y desactivar Webhooks

Es posible que desee deshabilitar temporalmente un webhook sin eliminarlo. Esto se puede hacer usando disable_webhook(), y el webhook se puede reactivar más adelante con 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)

Eliminar un Webhook

Cuando un webhook ya no es necesario, se puede eliminar de forma permanente usando delete_webhook().

from huggingface_hub import delete_webhook

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

Gestión de Webhooks desde la CLI

Todas las operaciones anteriores también están disponibles desde la interfaz de línea de comandos hf. Esto resulta especialmente útil para la creación de scripts y flujos de trabajo agénticos.

# 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>

La opción --watch utiliza el formato type:name, donde type es uno de model, dataset, space, org o user. Puede repetirse para supervisar varios elementos. Para obtener la lista completa de opciones, ejecute hf webhooks <command> --help. Para más detalles, consulte la guía de la CLI.

Servidor de Webhooks

La clase base que utilizaremos en esta sección de guías es WebhooksServer(). Es una clase para configurar fácilmente un servidor que puede recibir webhooks del Huggingface Hub. El servidor se basa en una aplicación de Gradio. Tiene una interfaz de usuario para mostrar instrucciones para ti o para tus usuarios y una API para escuchar webhooks.

Para ver un ejemplo en funcionamiento de un servidor de webhook, consulta el de Spaces CI Bot. Es un Space que lanza entornos efímeros cuando se abre un PR en un Space.

Esta es una función experimental. Esto significa que seguimos trabajando en la mejora de la API. Es posible que se introduzcan cambios que rompan la compatibilidad en el futuro sin previo aviso. Asegúrate de fijar la versión de huggingface_hub en tus requisitos.

Crear un punto de acceso

Implementar un punto de entrada de webhook es tan sencillo como decorar una función. Veamos un primer ejemplo para explicar los conceptos principales:

# 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
        ...

Guarda este fragmento en un archivo llamado 'app.py' y ejecútalo con 'python app.py'. Deberías ver un mensaje como este:

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.

¡Buen trabajo! Acabas de lanzar un servidor de webhooks. Desglosemos exactamente lo que ocurrió:

1. Al decorar una función con webhook_endpoint(), se ha creado un objeto WebhooksServer() en segundo plano. Como puede ver, este servidor es una aplicación de Gradio que se ejecuta en http://127.0.0.1:7860. Si abre esta URL en su navegador, verá una página de inicio con instrucciones sobre los webhooks registrados.
2. Una aplicación de Gradio es, en el fondo, un servidor de FastAPI. Se ha añadido una nueva ruta POST /webhooks/trigger_training. Esta es la ruta que escuchará los webhooks y ejecutará la función trigger_training cuando se active. FastAPI analizará automáticamente el payload y lo pasará a la función como un objeto WebhookPayload. Este es un objeto de pydantic que contiene toda la información sobre el evento que activó el webhook.
3. La aplicación de Gradio también abrió un túnel para recibir solicitudes desde internet. Esta es la parte interesante: puedes configurar un Webhook en https://huggingface.co/settings/webhooks que apunte a tu máquina local. Esto es útil para depurar tu servidor de webhooks e iterar rápidamente antes de desplegarlo en un Space.
4. Por último, los registros también indican que tu servidor actualmente no está protegido por un secreto. Esto no es un problema para la depuración local, pero conviene tenerlo en cuenta para más adelante.

Por defecto, el servidor se inicia al final de su script. Si lo está ejecutando en un notebook, puede iniciar el servidor manualmente llamando a decorated_function.launch(). Dado que se utiliza un servidor único, solo tiene que iniciar el servidor una vez, incluso si tiene múltiples puntos de acceso.

Configurar un Webhook

Ahora que tienes un servidor de webhook en ejecución, quieres configurar un Webhook para empezar a recibir mensajes. Ve a https://huggingface.co/settings/webhooks, haz clic en “Add a new webhook” y configura tu Webhook. Establece los repositorios objetivo que quieres vigilar y la URL del Webhook, en este caso https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training.

¡Y eso es todo! Ahora puedes activar ese webhook actualizando el repositorio de destino (por ejemplo, enviando un commit). Consulta la pestaña Activity de tu Webhook para ver los eventos que se han activado. Ahora que tienes una configuración funcional, puedes probarla e iterar rápidamente. Si modificas tu código y reinicias el servidor, es posible que tu URL pública cambie. Asegúrate de actualizar la configuración del webhook en el Hub si es necesario.

Desplegar en un Space

Ahora que tienes un servidor de webhook funcional, el objetivo es desplegarlo en un Space. Ve a https://huggingface.co/new-space para crear un Space. Asígname un nombre, selecciona el SDK de Gradio y haz clic en “Create Space”. Sube tu código al Space en un archivo llamado app.py. ¡Tu Space se iniciará automáticamente! Para más detalles sobre Spaces, consulta esta guía.

Tu servidor de webhook ahora se está ejecutando en un Space público. En la mayoría de los casos, querrás protegerlo con un secreto. Ve a la configuración de tu Space > Sección “Repository secrets” > “Add a secret”. Establece la variable de entorno WEBHOOK_SECRET con el valor que prefieras. Vuelve a la Webhooks settings y configura el secreto en la configuración del webhook. Ahora, solo se aceptarán las solicitudes con el secreto correcto en tu servidor.

¡Y listo! Tu Space ya está preparado para recibir webhooks desde el Hub. Ten en cuenta que si ejecutas el Space en un hardware gratuito de tipo ‘cpu-basic’, se cerrará tras 48 horas de inactividad. Si necesitas un Space permanente, deberías considerar cambiar a un hardware mejorado.

Uso avanzado

La guía anterior explicó la forma más rápida de configurar un WebhooksServer(). En esta sección, veremos cómo personalizarlo aún más.

Varios puntos finales

Puedes registrar varios puntos de conexión en el mismo servidor. Por ejemplo, es posible que quieras tener un punto de conexión para iniciar una tarea de entrenamiento y otro para iniciar la evaluación de un modelo. Puedes hacer esto añadiendo varios decoradores @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
        ...

Lo que creará dos puntos finales:

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

Servidor personalizado

Para obtener más flexibilidad, también puedes crear directamente un objeto WebhooksServer(). Esto es útil si quieres personalizar la página de inicio de tu servidor. Puedes hacerlo pasando una Gradio UI que sobrescribirá la predeterminada. Por ejemplo, puedes añadir instrucciones para tus usuarios o un formulario para activar manualmente los webhooks. Al crear un WebhooksServer(), puedes registrar nuevos webhooks usando el decorador add_webhook().

Aquí hay un ejemplo completo:

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. Definimos una interfaz de usuario personalizada usando bloques de Gradio. Esta interfaz se mostrará en la página de inicio del servidor.
2. Creamos un objeto WebhooksServer() con una interfaz de usuario personalizada y un secreto. El secreto es opcional y se puede establecer con la variable de entorno WEBHOOK_SECRET.
3. Registramos un webhook con un nombre explícito. Esto creará un punto de acceso en /webhooks/say_hello.
4. Registramos un webhook con un nombre implícito. Esto creará un punto de acceso en /webhooks/goodbye.
5. Iniciamos el servidor. Esto es opcional, ya que el servidor se iniciará automáticamente al final del script.