# Webhooks 서버

Webhooks는 MLOps 관련 기능의 기반입니다. 특정 저장소 또는 관심 있는 사용자/조직에 속한 모든 저장소에서 새로운 변경 사항을 수신할 수 있습니다. Huggingface Hub의 Webhooks에 대해 자세히 알아보려면 Webhooks [가이드](https://huggingface.co/docs/hub/webhooks)를 읽어보십시오.

> [!TIP]
> 웹훅 서버를 설정하고 Space로 배포하는 단계별 튜토리얼을 위한 [가이드](../guides/webhooks_server)를 확인해 보세요.

> [!WARNING]
> 이것은 실험적 기능입니다. 이는 API를 개선하기 위해 작업이 진행 중임을 의미합니다. 사전 통보 없이 향후 호환성이 깨지는 변경 사항이 도입될 수 있습니다. `huggingface_hub`의 버전을 요구 사항에 고정하도록 하십시오. 실험적 기능을 사용할 때 경고가 발생합니다. 환경 변수로 `HF_HUB_DISABLE_EXPERIMENTAL_WARNING=1`을 설정하여 이를 비활성화할 수 있습니다.

## 서버

서버는 [Gradio](https://gradio.app/) 앱입니다. 사용자에게 지침을 표시하는 UI와 웹훅을 수신하는 API를 제공합니다. 웹훅 엔드포인트 구현은 함수를 데코레이터로 장식하는 것만큼 간단합니다. Space에 배포하기 전에 Gradio 터널을 사용하여 웹훅을 로컬 머신으로 리디렉션하여 디버깅할 수 있습니다.

### 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`인 경우, 구성된 웹훅에 대한 지침을 표시하는 UI가 생성됩니다.

webhook_secret (`str`, optional) : 수신되는 webhook 요청을 검증하는 비밀 키입니다. [webhooks 설정 패널](https://huggingface.co/settings/webhooks)에도 동일한 값을 구성하는 한, 원하는 어떤 비밀 값으로든 이 값을 설정할 수 있습니다. 또한 이 값을 `WEBHOOK_SECRET` 환경 변수로 설정할 수도 있습니다. 비밀 값이 제공되지 않으면 보안 없이 webhook 엔드포인트가 열립니다.

[WebhooksServer()](/docs/huggingface_hub/v2.4.0/ko/package_reference/webhooks_server#huggingface_hub.WebhooksServer) 클래스를 사용하면 Huggingface 웹훅을 수신할 수 있는 Gradio 앱 인스턴스를 생성할 수 있습니다. 이러한 웹훅은 `add_webhook()` 데코레이터를 사용하여 등록할 수 있습니다. 웹훅 엔드포인트는 FastAPI 라우터에 POST 엔드포인트로 추가됩니다. 모든 웹훅이 등록되면 앱을 시작하려면 `launch` 메서드를 호출해야 합니다.

Webhook 함수의 첫 번째 인수로 [WebhookPayload](/docs/huggingface_hub/v2.4.0/ko/package_reference/webhooks_server#huggingface_hub.WebhookPayload)를 받는 것을 권장합니다. 이는 Webhook 이벤트에 대한 모든 정보를 포함하는 Pydantic 모델입니다. 데이터는 자동으로 파싱됩니다.

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`, optional) : webhook 함수를 등록할 URL 경로입니다. 제공되지 않으면 함수 이름이 경로로 사용됩니다. 모든 webhook은 `/webhooks` 아래에 등록됩니다.

[WebhooksServer()](/docs/huggingface_hub/v2.4.0/ko/package_reference/webhooks_server#huggingface_hub.WebhooksServer)를 시작하고 장식된 함수를 웹훅 엔드포인트로 등록하는 데코레이터입니다.

빠른 시작을 위한 헬퍼입니다. 더 많은 유연성(커스텀 랜딩 페이지 또는 웹훅 시크릿)이 필요하면 [WebhooksServer()](/docs/huggingface_hub/v2.4.0/ko/package_reference/webhooks_server#huggingface_hub.WebhooksServer)를 직접 사용할 수 있습니다. 이 데코레이터를 여러 번 사용하여 여러 웹훅 엔드포인트(같은 서버에)를 등록할 수 있습니다.

서버를 설정하고 Space에 배포하는 단계별 튜토리얼은 [webhooks 가이드](../guides/webhooks_server)를 참고하세요.

> [!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()
```

## Payload[[huggingface_hub.WebhookPayload]]

[WebhookPayload](/docs/huggingface_hub/v2.4.0/ko/package_reference/webhooks_server#huggingface_hub.WebhookPayload)는 Webhooks에서 전달되는 페이로드를 포함하는 주요 데이터 구조입니다. 이는 `pydantic` 클래스로, FastAPI와 함께 사용하기 매우 쉽습니다. 웹훅 엔드포인트의 매개변수로 전달하면 자동으로 검증되고 Python 객체로 파싱됩니다.

webhooks payload에 대한 자세한 내용은 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)