# Serveur de Webhooks

Les webhooks constituent un socle pour les fonctionnalités liées au MLOps. Ils vous permettent de surveiller les nouvelles modifications sur des dépôts spécifiques ou sur l’ensemble des dépôts appartenant à des utilisateurs ou organisations particuliers que vous souhaitez suivre. Pour en savoir plus sur les webhooks du Huggingface Hub, vous pouvez consulter le [guide](https://huggingface.co/docs/hub/webhooks) sur les webhooks.

> [!TIP]
> Consultez ce [guide](../guides/webhooks_server) pour un tutoriel étape par étape sur la configuration de votre serveur de webhooks et son déploiement en tant que Space.

> [!WARNING]
> Il s’agit d’une fonctionnalité expérimentale. Cela signifie que nous travaillons encore à améliorer l’API. Des modifications cassantes pourraient être introduites à l’avenir sans préavis. Veillez à épingler la version de `huggingface_hub` dans vos dépendances. Un avertissement est déclenché lorsque vous utilisez une fonctionnalité expérimentale. Vous pouvez le désactiver en définissant `HF_HUB_DISABLE_EXPERIMENTAL_WARNING=1` en tant que variable d’environnement.

## Serveur

Le serveur est une application [Gradio](https://gradio.app/). Il dispose d’une interface utilisateur pour afficher des instructions à vous ou à vos utilisateurs, ainsi que d’une API pour écouter les webhooks. La mise en œuvre d’un point de terminaison de webhook est aussi simple que de décorer une fonction. Vous pouvez ensuite la déboguer en redirigeant les Webhooks vers votre machine (à l’aide d’un tunnel Gradio) avant de la déployer sur un Space.

### WebhooksServer[[huggingface_hub.WebhooksServer]]

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

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

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

**Paramètres :**

ui (`gradio.Blocks`, optionnel) : Une instance d'interface Gradio à utiliser comme page d'accueil de l'Espace. Si `None`, une interface affichant les instructions relatives aux webhooks configurés est créée.

webhook_secret (`str`, optionnel) : Une clé secrète pour vérifier les requêtes webhook entrantes. Vous pouvez définir cette valeur avec n'importe quel secret, à condition de le configurer également dans votre [panneau de configuration des webhooks](https://huggingface.co/settings/webhooks). Vous pouvez également définir cette valeur en tant que variable d'environnement `WEBHOOK_SECRET`. Si aucun secret n'est fourni, les points de terminaison webhook sont ouverts sans aucune sécurité.

La classe [WebhooksServer()](/docs/huggingface_hub/v2.4.0/fr/package_reference/webhooks_server#huggingface_hub.WebhooksServer) permet de créer une instance d’application Gradio capable de recevoir des webhooks Huggingface. Ces webhooks peuvent être enregistrés à l’aide du décorateur `add_webhook()`. Les points de terminaison des webhooks sont ajoutés à l’application en tant que point de terminaison POST du routeur FastAPI. Une fois tous les webhooks enregistrés, la méthode `launch` doit être appelée pour démarrer l’application.

Il est recommandé d’accepter [WebhookPayload](/docs/huggingface_hub/v2.4.0/fr/package_reference/webhooks_server#huggingface_hub.WebhookPayload) comme premier argument de la fonction webhook. Il s’agit d’un modèle Pydantic contenant toutes les informations relatives à l’événement webhook. Les données seront analysées automatiquement pour vous.

Consultez le [guide des webhooks](../guides/webhooks_server) pour un tutoriel étape par étape sur la configuration de votre WebhooksServer et son déploiement sur un Space.

> [!WARNING]
> `WebhooksServer` est expérimental. Son API est susceptible d’évoluer à l’avenir.

> [!WARNING]
> Vous devez avoir `gradio` installé pour utiliser `WebhooksServer` (`pip install --upgrade gradio`).

Exemple :

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

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

**Paramètres :**

path (`str`, optionnel) : Le chemin d’URL pour enregistrer la fonction webhook. S’il n’est pas fourni, le nom de la fonction sera utilisé comme chemin. Dans tous les cas, tous les webhooks sont enregistrés sous `/webhooks`.

Décorateur pour démarrer un [WebhooksServer()](/docs/huggingface_hub/v2.4.0/fr/package_reference/webhooks_server#huggingface_hub.WebhooksServer) et enregistrer la fonction décorée en tant que point de terminaison de webhook.

Ceci est un utilitaire pour démarrer rapidement. Si vous avez besoin de plus de flexibilité (page d’accueil personnalisée ou secret de webhook), vous pouvez utiliser directement [WebhooksServer()](/docs/huggingface_hub/v2.4.0/fr/package_reference/webhooks_server#huggingface_hub.WebhooksServer). Vous pouvez enregistrer plusieurs points de terminaison de webhook (sur le même serveur) en utilisant ce décorateur plusieurs fois.

Consultez le [guide des webhooks](../guides/webhooks_server) pour un tutoriel étape par étape sur la configuration de votre serveur et son déploiement sur un Space.

> [!WARNING]
> `webhook_endpoint` est expérimental. Son API est susceptible d'évoluer à l'avenir.

> [!WARNING]
> Vous devez avoir `gradio` installé pour utiliser `webhook_endpoint` (`pip install --upgrade gradio`).

Exemples : l'utilisation par défaut consiste à enregistrer une fonction en tant que point de terminaison de webhook. Le nom de la fonction sera utilisé comme chemin. Le serveur sera démarré automatiquement à la sortie (c'est-à-dire à la fin du 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
        ...

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

Utilisation avancée : enregistrez une fonction en tant que point de terminaison de webhook et démarrez le serveur manuellement. Cela est utile si vous l’exécutez dans un notebook.

```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/fr/package_reference/webhooks_server#huggingface_hub.WebhookPayload) est la structure de données principale qui contient la charge utile des Webhooks. Il s’agit d’une classe `pydantic`, ce qui la rend très facile à utiliser avec FastAPI. Si vous la passez en paramètre à un point de terminaison de webhook, elle sera automatiquement validée et analysée en tant qu’objet Python.

Pour plus d’informations sur la charge utile des webhooks, vous pouvez consulter le guide [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)
```

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

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

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

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

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

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

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

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

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

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