# API: Webhooks, Events und Signaturen

_API · 7 Min. Lesezeit · Aktualisiert 2026-10-22 · https://lanachat.ai/guides/de/api-webhooks/_

Ein **Webhook** sendet ein HTTPS-`POST` an Ihren Server, wenn etwas im Workspace passiert: eine neue Konversation, ein Verkauf, ein Medium ist bereit, ein Konto hat die Verbindung verloren. Sie wählen die Events aus; LanaChat signiert jede Lieferung, damit Sie prüfen können, dass sie von uns stammt, und versucht es erneut, wenn Ihr Server nicht antwortet.

## Endpoints

| Method | Path | Description | Permission | Status |
|---|---|---|---|---|
| GET | `/webhooks` | List webhook endpoints | `owner` | Planned |
| POST | `/webhooks` | Add an endpoint: URL and events (the signing secret is shown once) | `owner` | Planned |
| GET | `/webhooks/{id}` | One endpoint and its delivery rate over 7 days | `owner` | Planned |
| PATCH | `/webhooks/{id}` | Change its URL or events, pause or resume it | `owner` | Planned |
| DELETE | `/webhooks/{id}` | Remove an endpoint | `owner` | Planned |
| POST | `/webhooks/{id}/rotate-secret` | New signing secret; the old one works 24 hours more | `owner` | Planned |
| POST | `/webhooks/{id}/test` | Send a `ping` event now | `owner` | Planned |
| GET | `/webhooks/{id}/deliveries` | Recent deliveries, their status and answer | `owner` | Planned |
| POST | `/webhooks/{id}/deliveries/{delivery_id}/retry` | Send one delivery again | `owner` | Planned |

## Events

| Event | Sent when | Permission the data needs |
|---|---|---|
| `conversation.started` | Ein Fan schreibt zum ersten Mal (mit `source_link_id`, wenn bekannt) | `can_fan_read` |
| `conversation.needs_review` | Eine Konversation erhält den Status Review oder Safety hold | `can_fan_read` |
| `conversation.taken_over` | Eine Person übernimmt eine Konversation oder gibt sie zurück | `can_fan_read` |
| `message.received` | Ein Fan sendet eine Nachricht | `can_fan_read` |
| `sale.completed` | Ein verifizierter Kauf (Stars oder Zahlungslink) | `can_sales_read` |
| `sale.refunded` | Eine Rückerstattung wird bestätigt | `can_sales_read` |
| `media.ready` | Ein hochgeladenes Medium ist verarbeitet oder fehlgeschlagen | `can_setup` |
| `account.health_changed` | Ein Konto wird verbunden, ausstehend oder abgelaufen | `can_setup` |
| `pool.saturated` | Ein Pool erreicht 95 % seiner stündlichen Kapazität oder das Workspace-Limit | `can_tracking` |
| `brain.published` | Ein Brain-Entwurf wird veröffentlicht | `can_engine` |
| `billing.low_balance` | Das Guthaben fällt unter den Betrag der nächsten 7 Tage Lizenzen | `owner` |
| `ping` | Sie haben Test gedrückt | none |

Ein Endpoint erhält ein Event nur, wenn das Token, das ihn erstellt hat, die Berechtigung hat, die die Daten benötigen.

## Das Webhook-Endpoint-Objekt

```json
{
  "id": "wh_12",
  "url": "https://hooks.mia-agency.com/lanachat/webhook",
  "events": ["sale.completed", "sale.refunded", "conversation.needs_review"],
  "status": "active",
  "delivery_rate_7d": 0.998,
  "created_at": "2026-10-01T09:00:00Z"
}
```

| Field | Type | Description |
|---|---|---|
| `id` | string | Der Endpoint |
| `url` | string | Ihre HTTPS-URL |
| `events` | array of strings | Die Events, die er empfängt (siehe Tabelle oben) |
| `status` | string | `active` oder `paused` (von Ihnen oder nach 3 Tagen Fehler) |
| `delivery_rate_7d` | number | Anteil der Lieferungen mit Antwort `2xx` über 7 Tage, 0 bis 1 |
| `created_at` | string | ISO 8601, UTC |

## Endpoints verwalten

Alle diese Aufrufe benötigen ein **owner**-Token.

### Einen Endpoint hinzufügen

`POST /webhooks` · `owner`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `url` | string | Ja | Eine HTTPS-URL Ihres Servers |
| `events` | array of strings | Ja | Die zu empfangenden Events |

```bash
curl -X POST https://api.lanachat.ai/v1/webhooks \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://hooks.mia-agency.com/lanachat/webhook", "events": ["sale.completed", "sale.refunded"]}'
```

Die Antwort ist der Endpoint (`201`) und sein **signing secret**, das nur in dieser Antwort angezeigt wird: Speichern Sie es sofort, neben Ihrem Token. Ein unbekannter Event-Name antwortet mit `400`.

### Auflisten, lesen, ändern und entfernen

| Call | What it does |
|---|---|
| `GET /webhooks` | Alle Endpoints des Workspaces |
| `GET /webhooks/{id}` | Ein Endpoint und seine Lieferquote über 7 Tage |
| `PATCH /webhooks/{id}` | Ändern von `url` oder `events`; pausieren oder fortsetzen mit `status` |
| `DELETE /webhooks/{id}` | Entfernen; es werden keine weiteren Daten gesendet |

```bash
curl -X PATCH https://api.lanachat.ai/v1/webhooks/wh_12 \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "active"}'
```

### Geheimnis rotieren

`POST /webhooks/{id}/rotate-secret` · `owner`

```bash
curl -X POST https://api.lanachat.ai/v1/webhooks/wh_12/rotate-secret \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
```

Die Antwort enthält das neue Secret, einmalig. Das alte funktioniert 24 Stunden weiter, damit Sie das neue ohne Lieferverluste einführen können.

### Einen Test senden

`POST /webhooks/{id}/test` · `owner`

```bash
curl -X POST https://api.lanachat.ai/v1/webhooks/wh_12/test \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
```

Ihr Server erhält innerhalb von Sekunden ein `ping`-Event, signiert wie jede andere Lieferung.

### Lieferungen und erneute Zustellung

`GET /webhooks/{id}/deliveries` listet die letzten Lieferungen, deren Status und die Antwort Ihres Servers. `POST /webhooks/{id}/deliveries/{delivery_id}/retry` sendet eine Lieferung erneut, z. B. nachdem Sie einen Fehler auf Ihrer Seite behoben haben.

```bash
curl -X POST https://api.lanachat.ai/v1/webhooks/wh_12/deliveries/dlv_5f21a9/retry \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
```

## Eine Lieferung

```http
POST /lanachat/webhook HTTP/1.1
Host: hooks.mia-agency.com
Content-Type: application/json
LanaChat-Event: sale.completed
LanaChat-Delivery: dlv_5f21a9
LanaChat-Signature: t=1759762800,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
```

```json
{
  "id": "evt_31877",
  "type": "sale.completed",
  "created_at": "2026-10-06T15:00:00Z",
  "workspace_id": "ws_7Hq2",
  "data": {
    "sale_id": "sale_8812", "fan_id": "fan_921", "creator_id": "cr_lea", "account_id": "acc_1001",
    "conversation_id": "conv_1001_88231", "stars": 300, "net_cents": 390, "sent_by": "ai", "kind": "offer"
  }
}
```

Jedes Event hat die gleiche Hülle: `id`, `type`, `created_at`, `workspace_id` und `data`. `data` enthält das Objekt, um das es im Event geht, mit den Feldern, die der passende API-Endpunkt zurückgibt.

## Payload jedes Events

`conversation.started`: die [Konversation](https://lanachat.ai/guides/de/api-conversations/), mit dem Link, von dem sie kam.

```json
{ "id": "evt_31801", "type": "conversation.started", "created_at": "2026-10-06T14:01:12Z", "workspace_id": "ws_7Hq2",
  "data": { "id": "conv_1001_88231", "fan_id": "fan_921", "creator_id": "cr_lea", "account_id": "acc_1001", "state": "ai", "source_link_id": "lnk_3" } }
```

`conversation.needs_review`: die Konversation und ihr neuer Status.

```json
{ "id": "evt_31840", "type": "conversation.needs_review", "created_at": "2026-10-06T14:20:00Z", "workspace_id": "ws_7Hq2",
  "data": { "id": "conv_1001_88231", "creator_id": "cr_lea", "account_id": "acc_1001", "state": "off", "status": { "tag": "review", "reason": "The fan asked for a refund." } } }
```

`conversation.taken_over`: wer die Konversation jetzt hält (`state` ist `human`, wenn eine Person sie übernimmt, `ai`, wenn sie zurückgegeben wird).

```json
{ "id": "evt_31852", "type": "conversation.taken_over", "created_at": "2026-10-06T14:04:00Z", "workspace_id": "ws_7Hq2",
  "data": { "id": "conv_1001_88231", "state": "human", "taken_by": "tok_31", "taken_at": "2026-10-06T14:04:00Z" } }
```

`message.received`: die Nachricht des Fans.

```json
{ "id": "evt_31860", "type": "message.received", "created_at": "2026-10-06T14:02:10Z", "workspace_id": "ws_7Hq2",
  "data": { "id": "msg_77119", "conversation_id": "conv_1001_88231", "from": "fan", "text": "show me more", "at": "2026-10-06T14:02:10Z" } }
```

`sale.completed` und `sale.refunded`: der Verkauf, wie in der obigen Lieferung. Eine Rückerstattung hat dieselbe `sale_id` wie der Verkauf, den sie storniert.

`media.ready`: das [Medium](https://lanachat.ai/guides/de/api-vault/), `status` `ready` oder `failed`.

```json
{ "id": "evt_31870", "type": "media.ready", "created_at": "2026-10-06T14:22:05Z", "workspace_id": "ws_7Hq2",
  "data": { "id": "med_5521", "creator_id": "cr_lea", "type": "photo", "status": "ready", "folder_id": "vf_3" } }
```

`account.health_changed`: das [Telegram-Konto](https://lanachat.ai/guides/de/api-telegram-accounts/) und sein neuer `health`-Status.

```json
{ "id": "evt_31881", "type": "account.health_changed", "created_at": "2026-10-06T15:10:00Z", "workspace_id": "ws_7Hq2",
  "data": { "id": "acc_1004", "creator_id": "cr_lea", "username": "lea_backup", "health": "expired" } }
```

`pool.saturated`: der [Pool](https://lanachat.ai/guides/de/api-telegram-accounts/) und seine Auslastung.

```json
{ "id": "evt_31890", "type": "pool.saturated", "created_at": "2026-10-06T21:00:00Z", "workspace_id": "ws_7Hq2",
  "data": { "id": "pool_lea_fr_instagram", "creator_id": "cr_lea", "sent_last_hour": 381, "capacity_per_hour": 400, "status": "saturated" } }
```

`brain.published`: das [Brain](https://lanachat.ai/guides/de/api-ai-brains/) und seine neue Version.

```json
{ "id": "evt_31901", "type": "brain.published", "created_at": "2026-10-06T14:20:03Z", "workspace_id": "ws_7Hq2",
  "data": { "id": "br_lea_main", "version": 13, "published_at": "2026-10-06T14:20:03Z" } }
```

`billing.low_balance`: Ihr [Guthaben](https://lanachat.ai/guides/de/api-billing/).

```json
{ "id": "evt_31910", "type": "billing.low_balance", "created_at": "2026-10-06T08:00:00Z", "workspace_id": "ws_7Hq2",
  "data": { "balance_cents": 2900 } }
```

`ping`: gesendet durch **Test**; `data` ist leer.

```json
{ "id": "evt_31920", "type": "ping", "created_at": "2026-10-06T16:00:00Z", "workspace_id": "ws_7Hq2", "data": {} }
```

## Signatur prüfen

`LanaChat-Signature` enthält einen Zeitstempel `t` und `v1`, den HMAC-SHA256 von `t + "." + raw body` mit dem Signing Secret Ihres Endpoints, in Hex.

In Node (beliebiges Framework, das Ihnen den rohen Body gibt):

```js
import { createHmac, timingSafeEqual } from 'node:crypto';

// rawBody: the request body as received (Buffer or string), before any JSON parsing
export function verify(rawBody, header, secret) {
  const parts = (header || '').split(',').map((p) => p.trim().split('='));
  const t = parts.find(([k]) => k === 't')?.[1];
  const signatures = parts.filter(([k]) => k === 'v1').map(([, v]) => v);   // two during a secret rotation
  if (!t || !(Math.abs(Date.now() / 1000 - Number(t)) < 300)) return false;  // older than 5 minutes: refuse
  const want = createHmac('sha256', secret).update(t + '.').update(rawBody).digest('hex');
  return signatures.some((v) => v.length === want.length && timingSafeEqual(Buffer.from(v), Buffer.from(want)));
}
```

Ein kompletter Receiver mit Express:

```js
import express from 'express';
import { verify } from './verify.js';

const app = express();
const seen = new Set();   // use your database in production

app.post('/lanachat/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  if (!verify(req.body, req.get('LanaChat-Signature'), process.env.LANACHAT_WEBHOOK_SECRET)) return res.sendStatus(400);
  const event = JSON.parse(req.body);
  res.sendStatus(200);                       // answer fast, work after
  if (seen.has(event.id)) return;            // the same event can arrive twice
  seen.add(event.id);
  if (event.type === 'sale.completed') console.log('New sale', event.data.stars, 'Stars for', event.data.creator_id);
});

app.listen(3000);
```

In Python mit Flask:

```python
import hashlib
import hmac
import json
import os
import time

from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ["LANACHAT_WEBHOOK_SECRET"].encode()

def verify(raw_body: bytes, header: str) -> bool:
    parts = [p.strip().split("=", 1) for p in (header or "").split(",") if "=" in p]
    t = next((v for k, v in parts if k == "t"), None)
    signatures = [v for k, v in parts if k == "v1"]  # two during a secret rotation
    if not t or abs(time.time() - int(t)) >= 300:    # older than 5 minutes: refuse
        return False
    want = hmac.new(SECRET, t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(want, v) for v in signatures)

@app.post("/lanachat/webhook")
def webhook():
    raw = request.get_data()
    if not verify(raw, request.headers.get("LanaChat-Signature")):
        abort(400)
    event = json.loads(raw)
    if event["type"] == "sale.completed":
        print("New sale", event["data"]["stars"], "Stars for", event["data"]["creator_id"])
    return "", 200
```

- Berechnen Sie die Signatur auf dem rohen Body, vor jeglichem JSON-Parsing.
- Lehnen Sie einen Zeitstempel ab, der älter als 5 Minuten ist: das verhindert Replay-Angriffe.
- Während einer Secret-Rotation tragen Lieferungen zwei `v1`-Werte; akzeptieren Sie einen davon.

## Wiederholungen

- Antworten Sie innerhalb von 10 Sekunden mit einem beliebigen `2xx`. Alles andere oder keine Antwort gilt als Fehler.
- Eine fehlgeschlagene Lieferung wird 8 Mal über ca. 24 Stunden erneut versucht (1 Min, 5 Min, 30 Min, 2 Std, 5 Std, 10 Std, 14 Std, 24 Std).
- Dasselbe Event kann zweimal ankommen: verwenden Sie `id`, um Duplikate zu ignorieren. Die Reihenfolge ist nicht garantiert: verwenden Sie `created_at`.
- Nach 3 Tagen Fehler wird der Endpoint pausiert und der Besitzer erhält eine E-Mail; setzen Sie ihn mit `PATCH /webhooks/{id}` fort.

## Verwandte Artikel

- [LanaChat API: Schnellstart, Authentifizierung und Fehler](https://lanachat.ai/guides/de/api-overview/)
- [API Schnellrezepte: kopieren, einfügen, ausführen](https://lanachat.ai/guides/de/api-recipes/)
- [API: Fans, Konversationen und Nachrichten](https://lanachat.ai/guides/de/api-conversations/)