Webhooks 自動化

Webhooksを使用すると、Hugging Face上の特定のリポジトリまたはバケット、または特定のユーザー/組織に属するすべてのリポジトリ（自分のリポジトリだけでなく、任意のリポジトリ）に対する新しい変更を監視できます。

huggingface_hub Python クライアントで create_webhook を使用して、Hugging Face リポジトリに変更が発生したときに Job をトリガーする Webhook を作成します:

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

バケットにファイルが追加または削除されたときにジョブを実行するには、バケットを監視します:

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

完全な例については、Jobsでバケット内の新しいファイルを処理するを参照してください。

Webhookは、以下の環境変数を使用してJobをトリガーします:

• WEBHOOK_PAYLOAD: JSON文字列としての完全なWebhookペイロード
• WEBHOOK_REPO_ID: リポジトリまたはバケット名（例: user/repo-name）
• WEBHOOK_REPO_TYPE: リポジトリの種類（model、dataset、space、またはbucket）
• WEBHOOK_SECRET: 設定されている場合のWebhookシークレット
• WEBHOOK_ID: その配信に割り当てられた一意の識別子。その配信のリトライ間でも安定しています

Webhookの実行では、Jobのボリュームやシークレットは保持されません。Jobに必要なシークレット（HF_TOKENなど）は、create_webhook内でsecrets=を指定して渡してください。WebhookからUVスクリプトを実行するには、hf jobs run <image> uv run <url>でJobを定義してください。それ以外の場合、hf jobs uv runはスクリプトをボリュームにアップロードしますが、Webhookの実行にはボリュームが存在しないため、実行できません。

Webhookペイロードには複数のフィールドが含まれており、以下にいくつかの有用なものを示します。

- 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

Webhookに関する詳細は、huggingface_hubのWebhooksドキュメントを参照してください。