# Créer un webhook (POST)

Créez un nouveau webhook pour recevoir des notifications push depuis des services externes.

## Point de terminaison

```
POST https://api.pocketalert.app/v1/webhooks
```

## Authentification

> **Info: Obligatoire**
>
> Incluez l’un de ces en-têtes dans votre requête :
> - `Token: <your-api-key>` — Obtenez-la depuis [Clés API](https://pocketalert.app/account/apikeys)
> - `Authorization: Bearer <jwt-token>` — Depuis [Connexion](https://info.pocketalert.app/api/user/login.md)

## Requête

### En-têtes

| En-tête | Obligatoire | Description |
|---------|:-----------:|-------------|
| `Token` | ✅ | Votre clé API |
| `Authorization` | ✅ | `Bearer <jwt-token>` |

### Paramètres du corps

| Paramètre | Type | Obligatoire | Description |
|-----------|------|:-----------:|-------------|
| `name` | string | ✅ | Nom du webhook (par ex. « Sentry », « GitHub ») |
| `url` | string | ❌ | Slug de l’URL de réception `https://p4a.me/wh/{url}`. Un slug aléatoire de 20 caractères est généré si ce champ est omis. Il doit être unique : un slug déjà pris renvoie `409` |
| `message` | string | ✅ | Modèle de message (utilisez `*` pour le JSON brut) |
| `application_id` | string | ❌ | TID de l’application pour classer les messages |
| `device_id` | string | ❌ | TID de l’appareil cible (omettez-le pour tous les appareils) |
| `default_level` | string \| int | ❌ | Niveau de priorité par défaut appliqué aux messages de ce webhook lorsque la charge utile n’en précise pas : un nom (`silent`, `low`, `default`, `high`, `critical`) ou un entier (`-2`..`2`). Voir [Niveaux de priorité des messages](https://info.pocketalert.app/api/messages/create.md#priority-levels). |
| `actions` | string | ❌ | Modèle JSON de boutons d’action. Même structure que les [actions de message](https://info.pocketalert.app/api/messages/create.md#action-buttons), mais `label`/`value` peuvent contenir des espaces réservés `%field.path%` résolus à partir de la charge utile entrante. Stocké sous forme de chaîne JSON. Fonctionnalité payante : supprimée sur l’offre gratuite. |

### Modèle de boutons d’action

`actions` permet aux notifications générées par le webhook de comporter jusqu’à 3 boutons, avec des espaces réservés `%field.path%` remplacés par les valeurs de la charge utile entrante (même syntaxe que le modèle de message) :

```json
[
  { "type": "view", "label": "Open issue", "value": "%issue.html_url%" },
  { "type": "http", "label": "Ack", "value": "{\"url\":\"https://ops.example.com/ack/%issue.id%\",\"method\":\"POST\"}" }
]
```

Le modèle est vérifié lors de l’enregistrement : il doit être un tableau JSON d’au plus 3 boutons, avec un `type` valide, et un bouton sans espace réservé doit être entièrement valide, sans quoi la requête renvoie `400`.

Après remplacement, chaque bouton est validé comme les [actions de message](https://info.pocketalert.app/api/messages/create.md#action-buttons). Un bouton devenu invalide pour cette charge utile, comme un bouton `view` dont le champ d’URL est absent, est supprimé à lui seul ; les autres boutons et le message sont tout de même envoyés.

Les boutons d’action sont une fonctionnalité payante. Sur l’offre gratuite, ils sont supprimés côté serveur et le message est envoyé sans eux.

### Syntaxe du modèle de message

Utilisez `%field.path%` pour extraire des valeurs du JSON entrant :

| Modèle | Description |
|--------|-------------|
| `*` | Affiche la charge utile JSON complète |
| `%field%` | Extrait un champ de premier niveau |
| `%object.field%` | Extrait un champ imbriqué |
| `%array.0.field%` | Extrait depuis un tableau par index |
| `%%` | Un `%` littéral. Nécessaire uniquement juste avant un mot suivi d’un autre `%`, comme dans `%cpu%%%` ; un `%` suivi d’une espace, comme dans `90% on %host%`, reste tel quel |

Consultez [Paramètres du webhook](https://info.pocketalert.app/api/webhooks/settings.md) pour des exemples détaillés.

### Exemple de requête

**cURL**

```bash
curl -X POST "https://api.pocketalert.app/v1/webhooks" \
  -H "Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GitHub Push",
    "message": "Push to %repository.name%: %head_commit.message%",
    "application_id": "s9h1ekk5xb46jikthl"
  }'
```

**JavaScript**

```javascript
const response = await fetch('https://api.pocketalert.app/v1/webhooks', {
  method: 'POST',
  headers: {
    'Token': 'your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'GitHub Push',
    message: 'Push to %repository.name%: %head_commit.message%',
    application_id: 's9h1ekk5xb46jikthl'
  })
});

const webhook = await response.json();
console.log('Webhook URL:', `https://p4a.me/wh/${webhook.url}`);
```

**Python**

```python
import requests

response = requests.post(
    'https://api.pocketalert.app/v1/webhooks',
    headers={'Token': 'your-api-key'},
    json={
        'name': 'GitHub Push',
        'message': 'Push to %repository.name%: %head_commit.message%',
        'application_id': 's9h1ekk5xb46jikthl'
    }
)

webhook = response.json()
print(f"Webhook URL: https://p4a.me/wh/{webhook['url']}")
```

**PHP**

```php
$response = Http::withHeaders([
    'Token' => 'your-api-key',
])->post('https://api.pocketalert.app/v1/webhooks', [
    'name' => 'GitHub Push',
    'message' => 'Push to %repository.name%: %head_commit.message%',
    'application_id' => 's9h1ekk5xb46jikthl',
]);

$webhook = $response->json();
echo 'Webhook URL: https://p4a.me/wh/'.$webhook['url'];
```

## Réponse

### Réponse de succès

> **Tip: 201 Created**
>
> Webhook créé avec succès

| Champ | Type | Description |
|-------|------|-------------|
| `tid` | string | Identifiant unique du webhook |
| `name` | string | Nom du webhook |
| `url` | string | Slug de l’URL du webhook — à utiliser dans les services externes |
| `message` | string | Modèle de message |
| `actions` | string | Modèle JSON des boutons d’action (vide si non défini) |
| `is_active` | boolean | Indique si le webhook est actif |

```json
{
  "tid": "kblf7mh9j8jjyeh4fx",
  "name": "GitHub Push",
  "url": "cs994rqfkk8ljngt",
  "message": "Push to %repository.name%: %head_commit.message%",
  "actions": "",
  "application_tid": "qm47b9pzxzx7applfd0",
  "device_tid": "",
  "is_active": true,
  "created_at": "01.09.2023 22:38:48"
}
```

> **Tip: Utiliser votre webhook**
>
> Configurez votre service externe pour envoyer une requête POST à :
> ```
> https://p4a.me/wh/{url}
> ```

### Réponses d’erreur

| Statut | Description |
|:------:|-------------|
| `400` | Requête incorrecte — `name` ou `message` manquant, `default_level` invalide ou modèle `actions` invalide |
| `401` | Non autorisé — jeton invalide ou manquant |
| `403` | Interdit — limite de webhooks de votre offre atteinte |
| `404` | Introuvable — `application_id` ou `device_id` inexistant |
| `409` | Conflit — le slug `url` est déjà pris |
