# Webhook-Verlauf (GET)

Ruf den Verlauf der eingehenden Anfragen an einen bestimmten Webhook ab — was gesendet wurde, was daraus gerendert wurde und ob eine Benachrichtigung zugestellt wurde.

## Endpunkt

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

## Authentifizierung

> **Info: Erforderlich**
>
> Füge einen dieser Header in deiner Anfrage hinzu:
> - `Token: <your-api-key>` — Hol ihn dir unter [API-Schlüssel](https://pocketalert.app/account/apikeys)
> - `Authorization: Bearer <jwt-token>` — Aus [Anmeldung](https://info.pocketalert.app/api/user/login.md)

## Anfrage

### Pfadparameter

| Parameter | Typ | Pflicht | Beschreibung |
|-----------|------|:--------:|-------------|
| `tid` | string | ✅ | Eindeutige ID des Webhooks |

### Abfrageparameter

| Parameter | Typ | Standard | Beschreibung |
|-----------|------|:-------:|-------------|
| `page` | integer | `1` | Seitennummer |
| `per` | integer | `50` | Einträge pro Seite (maximal `200`) |
| `status` | string | — | Nach Ergebnis filtern: `success` oder `error` |

### Beispielanfrage

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

## Antwort

### Erfolgreiche Antwort

> **Tip: 200 OK**
>
> Gibt eine paginierte Liste der Anfragen zurück, neueste zuerst

| Feld | Typ | Beschreibung |
|-------|------|-------------|
| `requests` | array | Gespeicherte Anfragen |
| `total` | integer | Gesamtzahl der Anfragen innerhalb des Aufbewahrungszeitraums |
| `page` | integer | Aktuelle Seite |
| `per` | integer | Einträge pro Seite |
| `retention_days` | integer | Wie viele Tage Verlauf dein Tarif speichert (`0` = unbegrenzt) |
| `webhook` | object | `tid`, `name`, `url`, `is_active` |

Jeder Eintrag in `requests`:

| Feld | Typ | Beschreibung |
|-------|------|-------------|
| `id` | integer | ID der Anfrage |
| `method` | string | HTTP-Methode des Absenders |
| `source_ip` | string | IP-Adresse des Aufrufers |
| `content_type` | string | Content-Type der Anfrage |
| `query` | string | Roher Query-String |
| `headers` | object | Anfrage-Header (sensible werden geschwärzt) |
| `body` | string | Nutzlast der Anfrage |
| `size` | integer | Größe der Nutzlast in Bytes |
| `status` | string | `success` oder `error` |
| `error_code` | string | Fehlerursache, bei Erfolg leer |
| `rendered_message` | string | Nachricht, die aus deiner Vorlage entstanden ist |
| `message_tid` | string | ID der erstellten Nachricht, bei Fehlschlag leer |
| `priority` | integer | Ermittelte Warnstufe |
| `duration_ms` | integer | Verarbeitungszeit |
| `created_at` | string | Zeitpunkt, zu dem die Anfrage eingegangen ist |

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

### Fehlercodes

Wenn `status` den Wert `error` hat, erklärt `error_code`, was passiert ist:

| Code | Bedeutung |
|------|---------|
| `inactive` | Der Webhook ist deaktiviert, daher wurde keine Benachrichtigung gesendet |
| `invalid_json` | Die Nutzlast konnte nicht als JSON gelesen werden |
| `empty_message` | Die Vorlage ergab einen leeren String — meist ein `%path%`, der in der Nutzlast nicht existiert |
| `encryption_failed` | Die Nachricht konnte nicht verschlüsselt werden |
| `save_failed` | Die Nachricht konnte nicht gespeichert werden |
| `daily_limit` | Das [Tageslimit für Nachrichten](https://info.pocketalert.app/features/daily-limits.md) des Kontos wurde erreicht. Der Aufruf erhielt `429` und es wurde keine Benachrichtigung gesendet; Nutzlast und gerenderte Nachricht werden hier trotzdem aufbewahrt |

### Fehlerantworten

| Status | Beschreibung |
|:------:|-------------|
| `401` | Nicht autorisiert — Token ungültig oder fehlt |
| `404` | Nicht gefunden — Webhook existiert nicht |

## Hinweise

> **Warning: Aufbewahrung**
>
> Der Verlauf wird je nach Tarif für eine begrenzte Anzahl von Tagen gespeichert (siehe `retention_days`): 7 Tage im kostenlosen Tarif, 30 im Starter, 90 im Medium und 365 im Large. Ältere Anfragen werden automatisch entfernt, ebenso die ältesten Einträge, sobald ein einzelner Webhook mehr als 1.000 aufgezeichnete Aufrufe hat.

> **Info: Datenschutz**
>
> Nutzlasten werden im Ruhezustand mit deinem persönlichen Schlüssel verschlüsselt, genauso wie Nachrichteninhalte. Authorization-, Cookie- und API-Schlüssel-Header werden vor der Speicherung durch `[redacted]` ersetzt.
