# Historique des webhooks (GET)

Récupérez l’historique des requêtes entrantes d’un webhook spécifique : ce qui a été envoyé, ce qui a été généré et si une alerte a été délivrée.

## Point de terminaison

```
GET https://api.pocketalert.app/v1/webhooks/{tid}/history
```

## 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

### Paramètres de chemin

| Paramètre | Type | Obligatoire | Description |
|-----------|------|:--------:|-------------|
| `tid` | string | ✅ | Identifiant unique du webhook |

### Paramètres de requête

| Paramètre | Type | Par défaut | Description |
|-----------|------|:-------:|-------------|
| `page` | integer | `1` | Numéro de page |
| `per` | integer | `50` | Éléments par page (maximum `200`) |
| `status` | string | — | Filtrer par résultat : `success` ou `error` |

### Exemple de requête

**cURL**

```bash
curl -X GET "https://api.pocketalert.app/v1/webhooks/kblf7mh9j8jjyeh4fx/history?per=25&status=error" \
  -H "Token: your-api-key"
```

**JavaScript**

```javascript
const tid = 'kblf7mh9j8jjyeh4fx';
const response = await fetch(`https://api.pocketalert.app/v1/webhooks/${tid}/history?per=25`, {
  headers: { 'Token': 'your-api-key' }
});
const history = await response.json();
```

**Python**

```python
import requests

tid = 'kblf7mh9j8jjyeh4fx'
response = requests.get(
    f'https://api.pocketalert.app/v1/webhooks/{tid}/history',
    headers={'Token': 'your-api-key'},
    params={'per': 25, 'status': 'error'}
)
print(response.json())
```

## Réponse

### Réponse en cas de succès

> **Tip: 200 OK**
>
> Renvoie une liste paginée des requêtes, de la plus récente à la plus ancienne

| Champ | Type | Description |
|-------|------|-------------|
| `requests` | array | Requêtes enregistrées |
| `total` | integer | Nombre total de requêtes dans la période de conservation |
| `page` | integer | Page courante |
| `per` | integer | Éléments par page |
| `retention_days` | integer | Nombre de jours d’historique conservés par votre offre (`0` = illimité) |
| `webhook` | object | `tid`, `name`, `url`, `is_active` |

Chaque élément de `requests` :

| Champ | Type | Description |
|-------|------|-------------|
| `id` | integer | Identifiant de la requête |
| `method` | string | Méthode HTTP utilisée par l’expéditeur |
| `source_ip` | string | Adresse IP de l’appelant |
| `content_type` | string | Type de contenu de la requête |
| `query` | string | Chaîne de requête brute |
| `headers` | object | En-têtes de la requête (les données sensibles sont masquées) |
| `body` | string | Contenu de la requête |
| `size` | integer | Taille du contenu en octets |
| `status` | string | `success` ou `error` |
| `error_code` | string | Raison de l’échec, vide en cas de succès |
| `rendered_message` | string | Message généré à partir de votre modèle |
| `message_tid` | string | Identifiant du message créé, vide en cas d’échec |
| `priority` | integer | Niveau d’alerte retenu |
| `duration_ms` | integer | Durée de traitement |
| `created_at` | string | Date de réception de la requête |

```json
{
  "requests": [
    {
      "id": 412,
      "method": "POST",
      "source_ip": "140.82.115.16",
      "content_type": "application/json",
      "query": "",
      "headers": { "User-Agent": "GitHub-Hookshot", "Authorization": "[redacted]" },
      "body": "{\"repository\":{\"name\":\"pocketalert\"}}",
      "size": 38,
      "status": "success",
      "error_code": "",
      "rendered_message": "Push to pocketalert",
      "message_tid": "yrst1db64dbbe7euurpmanhdy",
      "priority": 1,
      "duration_ms": 24,
      "created_at": "18.07.2026 16:45:06"
    }
  ],
  "total": 1,
  "page": 1,
  "per": 50,
  "retention_days": 90,
  "webhook": {
    "tid": "kblf7mh9j8jjyeh4fx",
    "name": "GitHub Push",
    "url": "cs994rqfkk8ljngt",
    "is_active": true
  }
}
```

### Codes d’erreur

Lorsque `status` vaut `error`, `error_code` explique ce qui s’est passé :

| Code | Signification |
|------|---------|
| `inactive` | Le webhook est désactivé, aucune alerte n’a donc été envoyée |
| `invalid_json` | Le contenu n’a pas pu être analysé comme du JSON |
| `empty_message` | Le modèle a donné une chaîne vide — généralement un `%path%` absent du contenu |
| `encryption_failed` | Le message n’a pas pu être chiffré |
| `save_failed` | Le message n’a pas pu être enregistré |
| `daily_limit` | La [limite quotidienne de messages](https://info.pocketalert.app/features/daily-limits.md) du compte a été atteinte. L’appel a reçu un `429` et aucune alerte n’a été envoyée ; le contenu et le message généré sont conservés ici |

### Réponses d’erreur

| Statut | Description |
|:------:|-------------|
| `401` | Non autorisé — Jeton invalide ou absent |
| `404` | Introuvable — Le webhook n’existe pas |

## Remarques

> **Warning: Conservation**
>
> L’historique est conservé pendant un nombre limité de jours selon votre offre (voir `retention_days`) : 7 jours sur l’offre gratuite, 30 sur Starter, 90 sur Medium et 365 sur Large. Les requêtes plus anciennes sont supprimées automatiquement, de même que les entrées les plus anciennes dès qu’un webhook dépasse 1 000 appels enregistrés.

> **Info: Confidentialité**
>
> Les contenus sont chiffrés au repos avec votre clé personnelle, de la même manière que le contenu des messages. Les en-têtes Authorization, cookie et clé API sont remplacés par `[redacted]` avant le stockage.
