Webhooks

Webhooks são a base para recursos relacionados a MLOps. Eles permitem que você acompanhe novas alterações em repositórios específicos ou em todos os repositórios pertencentes a usuários/organizações específicos que você deseja acompanhar. Este guia explicará primeiro como gerenciar webhooks programaticamente. Em seguida, veremos como usar o huggingface_hub para criar um servidor que ouça webhooks e implantá-lo em um Space.

Este guia pressupõe que você esteja familiarizado com o conceito de webhooks no Huggingface Hub. Para saber mais sobre os próprios webhooks, você deve ler primeiro este guia.

Gerenciando Webhooks

huggingface_hub permite que você gerencie seus webhooks de forma programática. Você pode listar seus webhooks existentes, criar novos e atualizar, habilitar, desabilitar ou excluí-los. Esta seção orienta você sobre os procedimentos usando as funções de API do Hugging Face Hub.

Criando um Webhook

Para criar um novo webhook, use create_webhook() e especifique a URL para onde os payloads devem ser enviados, quais eventos devem ser monitorados e, opcionalmente, defina um domínio e um segredo para segurança.

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

Um webhook também pode acionar a execução de um Job na infraestrutura do Hugging face, em vez de enviar o payload para uma URL. Nesse caso, é necessário passar o ID de um Job de origem.

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

O webhook aciona o Job com o payload do webhook na variável de ambiente WEBHOOK_PAYLOAD. Os segredos do Job de origem não são copiados para o webhook. Se o Job acionado precisar de segredos (por exemplo, HF_TOKEN), passe-os com secrets={"HF_TOKEN": "hf_***"}. Com update_webhook(), você deve passar job_id junto com secrets. Os segredos listados substituem os valores armazenados, uma string vazia remove um segredo e todos os outros segredos são mantidos. Para mais informações sobre Hugging Face Jobs, hardware disponível (CPU, GPU) e scripts UV, consulte a documentação de Jobs.

Listando Webhooks

Para ver todos os webhooks que você configurou, pode listá-los com list_webhooks(). Isso é útil para revisar seus IDs, URLs e status.

from huggingface_hub import list_webhooks

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

Atualizando um Webhook

Se você precisar alterar a configuração de um webhook existente, como a URL ou os eventos que ele monitora, você pode atualizá-lo 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"]
)

Ativando e desativando Webhooks

Você pode querer desabilitar temporariamente um webhook sem excluí-lo. Isso pode ser feito usando disable_webhook(), e o webhook pode ser reabilitado posteriormente com 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)

Excluindo um Webhook

Quando um webhook não é mais necessário, ele pode ser excluído permanentemente usando delete_webhook().

from huggingface_hub import delete_webhook

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

Gerenciando Webhooks pela CLI

Todas as operações acima também estão disponíveis na interface de linha de comando hf. Isso é especialmente útil para scripts e fluxos de trabalho 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>

A opção --watch usa o formato type:name, em que type é um dos valores model, dataset, space, org ou user. Ela pode ser repetida para monitorar vários itens. Para a lista completa de opções, execute hf webhooks <command> --help. Para mais detalhes, consulte o guia da CLI.

Servidor de Webhooks

A classe base que usaremos nesta seção de guias é WebhooksServer(). Trata-se de uma classe para configurar facilmente um servidor que pode receber webhooks do Huggingface Hub. O servidor é baseado em um aplicativo Gradio. Ele possui uma interface de usuário para exibir instruções para você ou seus usuários e uma API para ouvir webhooks.

Para ver um exemplo funcional de um servidor de webhook, confira o Spaces CI Bot. É um Space que inicia ambientes efêmeros quando um PR é aberto em um Space.

Esta é uma funcionalidade experimental. Isso significa que ainda estamos trabalhando para melhorar a API. Alterações que quebram a compatibilidade podem ser introduzidas no futuro sem aviso prévio. Certifique-se de fixar a versão de huggingface_hub nos seus requisitos.

Criar um endpoint

Implementar um endpoint de webhook é tão simples quanto decorar uma função. Vamos ver um primeiro exemplo para explicar os principais conceitos:

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

Salve este trecho em um arquivo chamado 'app.py' e execute-o com 'python app.py'. Você deve ver uma mensagem como esta:

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.

Bom trabalho! Você acabou de lançar um servidor de webhook! Vamos detalhar exatamente o que aconteceu:

1. Ao decorar uma função com webhook_endpoint(), um objeto WebhooksServer() é criado em segundo plano. Como você pode ver, este servidor é um aplicativo Gradio executado em http://127.0.0.1:7860. Se você abrir esta URL no seu navegador, verá uma página inicial com instruções sobre os webhooks registrados.
2. Um aplicativo Gradio é um servidor FastAPI por baixo dos panos. Uma nova rota POST /webhooks/trigger_training foi adicionada a ele. Esta é a rota que vai ouvir os webhooks e executar a função trigger_training quando acionada. O FastAPI vai analisar automaticamente o payload e passá-lo para a função como um objeto WebhookPayload. Este é um objeto pydantic que contém todas as informações sobre o evento que acionou o webhook.
3. O aplicativo Gradio também abriu um túnel para receber solicitações da internet. Esta é a parte interessante: você pode configurar um Webhook em https://huggingface.co/settings/webhooks apontando para sua máquina local. Isso é útil para depurar seu servidor de webhook e iterar rapidamente antes de implantá-lo em um Space.
4. Por fim, os logs também informam que seu servidor atualmente não é protegido por um segredo. Isso não é problemático para depuração local, mas é algo a ter em mente para o futuro.

Por padrão, o servidor é iniciado no final do seu script. Se você estiver executando-o em um notebook, pode iniciar o servidor manualmente chamando decorated_function.launch(). Como um servidor único é usado, você só precisa iniciar o servidor uma vez, mesmo que tenha múltiplos endpoints.

Configure um Webhook

Agora que você tem um servidor de webhook em execução, deseja configurar um Webhook para começar a receber mensagens. Acesse https://huggingface.co/settings/webhooks, clique em “Add a new webhook” e configure seu Webhook. Defina os repositórios de destino que você deseja monitorar e a URL do Webhook, aqui https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training.

E é isso! Agora você pode acionar esse webhook atualizando o repositório de destino (por exemplo, enviando um commit). Verifique a aba Activity do seu Webhook para ver os eventos que foram acionados. Agora que você tem uma configuração funcional, pode testá-la e iterar rapidamente. Se você modificar seu código e reiniciar o servidor, sua URL pública pode mudar. Certifique-se de atualizar a configuração do webhook no Hub, se necessário.

Implantar em um Space

Agora que você tem um servidor de webhook funcional, o objetivo é implantá-lo em um Space. Acesse https://huggingface.co/new-space para criar um Space. Dê um nome a ele, selecione o SDK Gradio e clique em “Create Space”. Envie seu código para o Space em um arquivo chamado app.py. Seu Space será iniciado automaticamente! Para mais detalhes sobre Spaces, consulte este guia.

Seu servidor de webhook agora está em execução em um Space público. Na maioria dos casos, você desejará protegê-lo com um segredo. Vá para as configurações do seu Space > Seção “Repository secrets” > “Add a secret”. Defina a variável de ambiente WEBHOOK_SECRET com o valor de sua escolha. Volte para as Webhooks settings e defina o segredo na configuração do webhook. Agora, apenas solicitações com o segredo correto serão aceitas pelo seu servidor.

E é isso! Seu Space está pronto para receber webhooks do Hub. Lembre-se de que, se você executar o Space em um hardware gratuito 'cpu-basic', ele será desligado após 48 horas de inatividade. Se você precisar de um Space permanente, considere definir um hardware aprimorado.

Uso avançado

O guia acima explicou a maneira mais rápida de configurar um WebhooksServer(). Nesta seção, veremos como personalizá-lo ainda mais.

Vários endpoints

Você pode registrar vários endpoints no mesmo servidor. Por exemplo, você pode querer ter um endpoint para acionar um trabalho de treinamento e outro para acionar uma avaliação de modelo. Você pode fazer isso adicionando vários 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
        ...

Isso criará dois endpoints:

(...)
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 obter mais flexibilidade, você também pode criar um objeto WebhooksServer() diretamente. Isso é útil se você quiser personalizar a página inicial do seu servidor. Você pode fazer isso passando uma Gradio UI que substituirá a padrão. Por exemplo, você pode adicionar instruções para seus usuários ou adicionar um formulário para acionar manualmente os webhooks. Ao criar um WebhooksServer(), você pode registrar novos webhooks usando o decorador add_webhook().

Aqui está um exemplo 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 uma interface de usuário personalizada usando blocos do Gradio. Essa interface será exibida na página inicial do servidor.
2. Criamos um objeto WebhooksServer() com uma interface personalizada e um segredo. O segredo é opcional e pode ser definido com a variável de ambiente WEBHOOK_SECRET.
3. Registramos um webhook com um nome explícito. Isso criará um endpoint em /webhooks/say_hello.
4. Registramos um webhook com um nome implícito. Isso criará um endpoint em /webhooks/goodbye.
5. Iniciamos o servidor. Isso é opcional, pois o seu servidor será iniciado automaticamente no final do script.