Automação de Webhooks

Webhooks permitem que você monitore novas alterações em repositórios ou buckets específicos, ou em todos os repositórios pertencentes a um conjunto particular de usuários/organizações (não apenas seus repositórios, mas qualquer repositório) no Hugging Face.

Use create_webhook no cliente Python huggingface_hub para criar um webhook que aciona um Job quando uma alteração ocorre em um repositório do Hugging Face:

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

Para executar um Job quando arquivos são adicionados ou excluídos de um bucket, monitore o bucket:

webhook = create_webhook(
    job_id=job_id,
    watched=[{"type": "bucket", "name": "your-username/your-bucket"}],
    domains=["repo"],
    secrets={"HF_TOKEN": "hf_***"},
)

Para um exemplo completo, consulte Processar novos arquivos em um bucket com Jobs.

O webhook aciona o Job com as seguintes variáveis de ambiente:

• WEBHOOK_PAYLOAD: o payload completo do webhook como uma string JSON
• WEBHOOK_REPO_ID: o nome do repositório ou bucket (por exemplo, user/repo-name)
• WEBHOOK_REPO_TYPE: o tipo de repositório (model, dataset, space ou bucket)
• WEBHOOK_SECRET: o segredo do webhook, caso tenha sido configurado
• WEBHOOK_ID: um identificador único para a entrega, estável entre as tentativas de repetição dessa entrega

A execução de um webhook não mantém os volumes nem os segredos do Job. Passe os segredos de que o Job precisa, como HF_TOKEN, com secrets= em create_webhook. Para executar um script UV a partir de um webhook, defina seu job com hf jobs run <image> uv run <url>; caso contrário, hf jobs uv run faz o upload do script para um volume, o qual uma execução de webhook não possui.

O payload do webhook contém vários campos; aqui estão alguns úteis:

- event:
  - action: one of "create", "delete", "move", "update"
  - scope: string
- repo:
  - owner: string
  - headSha: string (not sent for buckets)
  - name: string
  - type: one of "dataset", "model", "space", "bucket"
- updatedFiles: for bucket file changes, the list of added and deleted files

Você pode encontrar mais informações sobre webhooks na documentação de Webhooks do huggingface_hub.