# Webhooks サーバー

WebhooksはMLOps関連の機能の基盤です。特定のリポジトリ、またはフォローしたい特定のユーザー/組織に属するすべてのリポジトリでの変更を監視できます。Huggingface HubにおけるWebhooksの詳細については、Webhooksの[ガイド](https://huggingface.co/docs/hub/webhooks)をご覧ください。

> [!TIP]
> WebhookサーバーのセットアップとSpaceへのデプロイ方法をステップバイステップで解説したこの[ガイド](../guides/webhooks_server)をご覧ください。

> [!WARNING]
> これは実験的な機能です。つまり、APIの改善を継続的に進めている段階です。事前の通知なしに、将来破壊的変更が導入される可能性があります。`huggingface_hub`のバージョンをrequirementsに固定してください。実験的な機能を使用すると警告が表示されます。環境変数として`HF_HUB_DISABLE_EXPERIMENTAL_WARNING=1`を設定することで、この警告を無効にできます。

## サーバー

サーバーは[Gradio](https://gradio.app/)アプリです。あなたやユーザー向けの指示を表示するUIと、WebhookをリッスンするAPIを備えています。Webhookエンドポイントの実装は、関数にデコレータを付与するだけで済みます。その後、Gradioトンネルを使用してWebhookを自分のマシンにリダイレクトすることでデバッグし、Spaceにデプロイする前に確認できます。

### WebhooksServer[[huggingface_hub.WebhooksServer]]

#### huggingface_hub.WebhooksServer[[huggingface_hub.WebhooksServer]]

```python
huggingface_hub.WebhooksServer(*args, **kwargs)
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_webhooks_server.py#L37)

**パラメータ:**

ui (`gradio.Blocks`、省略可) : Space のランディングページとして使用する Gradio UI インスタンス。`None` の場合、設定された Webhook に関する説明を表示する UI が作成されます。

webhook_secret (`str`, 省略可能) : 受信した Webhook リクエストを検証するための秘密鍵です。[Webhook 設定パネル](https://huggingface.co/settings/webhooks)でも同じ値を設定している限り、任意の秘密値を指定できます。また、この値を `WEBHOOK_SECRET` 環境変数として設定することもできます。秘密鍵が指定されない場合、Webhook エンドポイントはセキュリティなしで公開されます。

[WebhooksServer()](/docs/huggingface_hub/v2.4.0/ja/package_reference/webhooks_server#huggingface_hub.WebhooksServer) クラスを使用すると、Huggingface の Webhook を受信できる Gradio アプリのインスタンスを作成できます。これらの Webhook は、`add_webhook()` デコレーターを使用して登録できます。Webhook エンドポイントは、FastAPI ルーターへの POST エンドポイントとしてアプリに追加されます。すべての Webhook の登録が完了したら、アプリを開始するために `launch` メソッドを呼び出す必要があります。

Webhook関数の第1引数として[WebhookPayload](/docs/huggingface_hub/v2.4.0/ja/package_reference/webhooks_server#huggingface_hub.WebhookPayload)を受け取ることをお勧めします。これはPydanticモデルであり、Webhookイベントに関するすべての情報を含んでいます。データは自動的にパースされます。

WebhooksServer の設定方法と Space へのデプロイ方法をステップバイステップで解説したチュートリアルは、[webhooks ガイド](../guides/webhooks_server)を参照してください。

> [!WARNING]
> `WebhooksServer` は実験的な機能です。将来、API が変更される可能性があります。

> [!WARNING]
> `WebhooksServer` を使用するには、`gradio` のインストールが必要です（`pip install --upgrade gradio`）。

例:

```python
import gradio as gr
from huggingface_hub import WebhooksServer, WebhookPayload

with gr.Blocks() as ui:
    ...

app = WebhooksServer(ui=ui, webhook_secret="my_secret_key")

@app.add_webhook("/say_hello")
async def hello(payload: WebhookPayload):
    return {"message": "hello"}

app.launch()
```

### @webhook_endpoint[[huggingface_hub.webhook_endpoint]]

#### huggingface_hub.webhook_endpoint[[huggingface_hub.webhook_endpoint]]

```python
huggingface_hub.webhook_endpoint(path: str | None = None)
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_webhooks_server.py#L221)

**パラメータ:**

path (`str`, 任意) : Webhook 関数を登録するための URL パスです。指定しない場合、関数名がパスとして使用されます。いずれの場合も、すべての Webhook は `/webhooks` 配下に登録されます。

[WebhooksServer()](/docs/huggingface_hub/v2.4.0/ja/package_reference/webhooks_server#huggingface_hub.WebhooksServer) を開始し、装飾された関数を Web フックのエンドポイントとして登録するためのデコレーターです。

これはクイックスタートのためのヘルパーです。より高い柔軟性（カスタムランディングページやWebhookシークレットなど）が必要な場合は、[WebhooksServer()](/docs/huggingface_hub/v2.4.0/ja/package_reference/webhooks_server#huggingface_hub.WebhooksServer)を直接使用できます。このデコレーターを複数回使用することで、複数のWebhookエンドポイントを（同じサーバーに）登録できます。

サーバーのセットアップとSpaceへのデプロイ方法をステップバイステップで解説したチュートリアルは、[webhooksガイド](../guides/webhooks_server)をご覧ください。

> [!WARNING]
> `webhook_endpoint` は実験的な機能です。将来、API が変更される可能性があります。

> [!WARNING]
> `webhook_endpoint` を使用するには、`gradio` のインストールが必要です（`pip install --upgrade gradio`）。

例: デフォルトの使用方法は、関数をWebhookエンドポイントとして登録することです。関数名がパスとして使用されます。サーバーは終了時(つまり、スクリプトの末尾)に自動的に起動されます。

```python
from huggingface_hub import webhook_endpoint, WebhookPayload

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

# Server is automatically started at the end of the script.
```

高度な使い方: 関数をWebhookエンドポイントとして登録し、サーバーを手動で開始します。これはノートブックで実行する場合に便利です。

```python
from huggingface_hub import webhook_endpoint, WebhookPayload

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

# Start the server manually
trigger_training.launch()
```

## ペイロード[[huggingface_hub.WebhookPayload]]

[WebhookPayload](/docs/huggingface_hub/v2.4.0/ja/package_reference/webhooks_server#huggingface_hub.WebhookPayload)は、Webhookからのペイロードを含む主要なデータ構造です。これは`pydantic`クラスであり、FastAPIとの連携が非常に容易です。Webhookエンドポイントのパラメータとして渡すと、自動的に検証され、Pythonオブジェクトとして解析されます。

Webhooksペイロードの詳細については、Webhooks Payloadの[ガイド](https://huggingface.co/docs/hub/webhooks#webhook-payloads)を参照してください。

#### huggingface_hub.WebhookPayload[[huggingface_hub.WebhookPayload]]

```python
huggingface_hub.WebhookPayload(event: WebhookPayloadEvent, repo: WebhookPayloadRepo, discussion: huggingface_hub._webhooks_payload.WebhookPayloadDiscussion | None = None, comment: huggingface_hub._webhooks_payload.WebhookPayloadComment | None = None, webhook: WebhookPayloadWebhook, movedTo: huggingface_hub._webhooks_payload.WebhookPayloadMovedTo | None = None, updatedRefs: list[huggingface_hub._webhooks_payload.WebhookPayloadUpdatedRef] | None = None)
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_webhooks_payload.py#L129)

### WebhookPayload[[huggingface_hub.WebhookPayload]]

#### huggingface_hub.WebhookPayload[[huggingface_hub.WebhookPayload]]

```python
huggingface_hub.WebhookPayload(event: WebhookPayloadEvent, repo: WebhookPayloadRepo, discussion: huggingface_hub._webhooks_payload.WebhookPayloadDiscussion | None = None, comment: huggingface_hub._webhooks_payload.WebhookPayloadComment | None = None, webhook: WebhookPayloadWebhook, movedTo: huggingface_hub._webhooks_payload.WebhookPayloadMovedTo | None = None, updatedRefs: list[huggingface_hub._webhooks_payload.WebhookPayloadUpdatedRef] | None = None)
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_webhooks_payload.py#L129)

### WebhookPayloadComment[[huggingface_hub.WebhookPayloadComment]]

#### huggingface_hub.WebhookPayloadComment[[huggingface_hub.WebhookPayloadComment]]

```python
huggingface_hub.WebhookPayloadComment(id: str, author: ObjectId, hidden: bool, content: str | None = None, url: WebhookPayloadUrl)
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_webhooks_payload.py#L94)

### WebhookPayloadDiscussion[[huggingface_hub.WebhookPayloadDiscussion]]

#### huggingface_hub.WebhookPayloadDiscussion[[huggingface_hub.WebhookPayloadDiscussion]]

```python
huggingface_hub.WebhookPayloadDiscussion(id: str, num: int, author: ObjectId, url: WebhookPayloadUrl, title: str, isPullRequest: bool, status: typing.Literal['closed', 'draft', 'open', 'merged'], changes: huggingface_hub._webhooks_payload.WebhookPayloadDiscussionChanges | None = None, pinned: bool | None = None)
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_webhooks_payload.py#L101)

### WebhookPayloadDiscussionChanges[[huggingface_hub.WebhookPayloadDiscussionChanges]]

#### huggingface_hub.WebhookPayloadDiscussionChanges[[huggingface_hub.WebhookPayloadDiscussionChanges]]

```python
huggingface_hub.WebhookPayloadDiscussionChanges(base: str, mergeCommitId: str | None = None)
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_webhooks_payload.py#L89)

### WebhookPayloadEvent[[huggingface_hub.WebhookPayloadEvent]]

#### huggingface_hub.WebhookPayloadEvent[[huggingface_hub.WebhookPayloadEvent]]

```python
huggingface_hub.WebhookPayloadEvent(action: typing.Literal['create', 'delete', 'move', 'update'], scope: str)
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_webhooks_payload.py#L84)

### WebhookPayloadMovedTo[[huggingface_hub.WebhookPayloadMovedTo]]

#### huggingface_hub.WebhookPayloadMovedTo[[huggingface_hub.WebhookPayloadMovedTo]]

```python
huggingface_hub.WebhookPayloadMovedTo(name: str, owner: ObjectId)
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_webhooks_payload.py#L75)

### WebhookPayloadRepo[[huggingface_hub.WebhookPayloadRepo]]

#### huggingface_hub.WebhookPayloadRepo[[huggingface_hub.WebhookPayloadRepo]]

```python
huggingface_hub.WebhookPayloadRepo(id: str, owner: ObjectId, head_sha: str | None = None, name: str, private: bool, subdomain: str | None = None, tags: list[str] | None = None, type: typing.Literal['dataset', 'model', 'space'], url: WebhookPayloadUrl)
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_webhooks_payload.py#L112)

### WebhookPayloadUrl[[huggingface_hub.WebhookPayloadUrl]]

#### huggingface_hub.WebhookPayloadUrl[[huggingface_hub.WebhookPayloadUrl]]

```python
huggingface_hub.WebhookPayloadUrl(web: str, api: str | None = None)
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_webhooks_payload.py#L70)

### WebhookPayloadWebhook[[huggingface_hub.WebhookPayloadWebhook]]

#### huggingface_hub.WebhookPayloadWebhook[[huggingface_hub.WebhookPayloadWebhook]]

```python
huggingface_hub.WebhookPayloadWebhook(id: str, version: typing.Literal[3])
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_webhooks_payload.py#L80)