# Сервер вебхуков

Webhooks являются основой для функций, связанных с MLOps. Они позволяют отслеживать новые изменения в конкретных репозиториях или во всех репозиториях, принадлежащих определённым пользователям или организациям, за которыми вы хотите следить. Чтобы узнать больше о webhooks на Huggingface Hub, вы можете прочитать [руководство](https://huggingface.co/docs/hub/webhooks) по Webhooks.

> [!TIP]
> Ознакомьтесь с этим [руководством](../guides/webhooks_server) с пошаговым описанием того, как настроить сервер вебхуков и развернуть его как Space.

> [!WARNING]
> Это экспериментальная функция. Это означает, что мы продолжаем дорабатывать API. В будущем могут быть внесены изменения, нарушающие обратную совместимость, без предварительного уведомления. Убедитесь, что вы зафиксировали версию `huggingface_hub` в своих зависимостях. При использовании экспериментальной функции выводится предупреждение. Вы можете отключить его, задав переменную окружения `HF_HUB_DISABLE_EXPERIMENTAL_WARNING=1`.

## Сервер

Сервер представляет собой приложение [Gradio](https://gradio.app/). В нём есть интерфейс для отображения инструкций для вас или ваших пользователей, а также API для приёма вебхуков. Реализация конечной точки вебхука сводится к декорированию функции. Затем вы можете отладить её, перенаправив вебхуки на ваш компьютер (используя туннель Gradio), прежде чем развернуть приложение в 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`, optional) : Экземпляр интерфейса Gradio, используемый в качестве главной страницы Space. Если `None`, создаётся интерфейс с инструкциями по настроенным вебхукам.

webhook_secret (`str`, optional) : Секретный ключ для проверки входящих запросов вебхука. Вы можете задать любое значение, при условии, что оно также будет настроено в вашем [панели настроек вебхуков](https://huggingface.co/settings/webhooks). Также это значение можно задать переменной окружения `WEBHOOK_SECRET`. Если секретный ключ не указан, эндпоинты вебхука будут открыты без какой-либо защиты.

Класс [WebhooksServer()](/docs/huggingface_hub/v2.4.0/ru/package_reference/webhooks_server#huggingface_hub.WebhooksServer) позволяет создать экземпляр приложения Gradio, который может принимать вебхуки Huggingface. Эти вебхуки регистрируются с помощью декоратора `add_webhook()`. Конечные точки вебхуков добавляются в приложение как POST-конечные точки для маршрутизатора FastAPI. После регистрации всех вебхуков необходимо вызвать метод `launch`, чтобы запустить приложение.

Рекомендуется принимать [WebhookPayload](/docs/huggingface_hub/v2.4.0/ru/package_reference/webhooks_server#huggingface_hub.WebhookPayload) в качестве первого аргумента функции вебхука. Это модель Pydantic, содержащая всю информацию о событии вебхука. Данные будут распарсены автоматически.

Ознакомьтесь с [руководством по вебхукам](../guides/webhooks_server), где пошагово описано, как настроить WebhooksServer и развернуть его на Space.

> [!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`, optional) : URL-путь для регистрации функции вебхука. Если не указан, в качестве пути будет использовано имя функции. В любом случае все вебхуки регистрируются под `/webhooks`.

Декоратор для запуска [WebhooksServer()](/docs/huggingface_hub/v2.4.0/ru/package_reference/webhooks_server#huggingface_hub.WebhooksServer) и регистрации декорируемой функции в качестве вебхук-эндпоинта.

Это вспомогательный инструмент для быстрого старта. Если вам нужна большая гибкость (например, собственная страница-заглушка или секрет вебхука), вы можете использовать [WebhooksServer()](/docs/huggingface_hub/v2.4.0/ru/package_reference/webhooks_server#huggingface_hub.WebhooksServer) напрямую. Вы можете зарегистрировать несколько конечных точек вебхуков (на одном и том же сервере), используя этот декоратор несколько раз.

См. [руководство по вебхукам](../guides/webhooks_server) с пошаговым руководством по настройке сервера и его развертыванию в Space.

> [!WARNING]
> `webhook_endpoint` является экспериментальным. Его API может измениться в будущем.

> [!WARNING]
> Для использования `webhook_endpoint` необходимо установить `gradio` (`pip install --upgrade gradio`).

Примеры: По умолчанию функция регистрируется как вебхук-эндпоинт. Имя функции используется в качестве пути. Сервер запускается автоматически при завершении работы (то есть в конце скрипта).

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

Расширенное использование: зарегистрируйте функцию в качестве конечной точки вебхука и запустите сервер вручную. Это полезно, если вы работаете в ноутбуке.

```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/ru/package_reference/webhooks_server#huggingface_hub.WebhookPayload) — это основная структура данных, содержащая полезную нагрузку от Webhooks. Это класс `pydantic`, что делает его очень удобным для использования с FastAPI. Если передать его в качестве параметра в endpoint вебхука, он будет автоматически валидирован и распарсен как объект Python.

Для получения дополнительной информации о содержимом вебхуков обратитесь к [руководству](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)