# Ereignisse per Webhook empfangen

> Ereignisse, Aufbau der Anfrage, Signaturprüfung und Wiederholungen. Im Team- und Business-Plan.

Ein Webhook schickt einen HTTPS-`POST` an deinen Server, wenn in deinem Workspace etwas passiert, zum Beispiel wenn ein Gespräch beginnt oder sich ein Kontakt ändert. Du richtest Webhooks unter **Einstellungen → Workspace → API & Webhooks → Webhook hinzufügen** ein.

Webhooks gehören zum Team-Plan (5 Endpunkte) und zum Business-Plan (25 Endpunkte). Nur Owner und Admins können sie verwalten.

## Ereignisse

| Ereignis | Wird gesendet, wenn |
| --- | --- |
| conversation.created | ein Gespräch beginnt |
| conversation.updated | sich Status, Zuweisung oder Labels eines Gesprächs ändern |
| conversation.closed | ein Gespräch erledigt ist |
| message.created | eine neue Nachricht ankommt oder gesendet wird. Interne Notizen sind nicht dabei. |
| contact.created | ein Kontakt gespeichert wird |
| contact.updated | sich ein Kontakt ändert |
| rating.created | ein Besucher ein Gespräch bewertet |

**Test senden** schickt ein `webhook.test`\-Ereignis, damit du deinen Endpunkt prüfen kannst. Abonnieren kannst du es nicht.

## Die Anfrage

Jede Anfrage ist ein `POST` mit JSON-Body:

```json
{
  "id": "cm3x9…",
  "event": "conversation.created",
  "createdAt": "2026-11-06T09:12:44.120Z",
  "workspaceId": "cm1a2…",
  "data": { }
}
```

`data` enthält das Objekt, um das es geht. Die genauen Felder siehst du, wenn du den Webhook öffnest, zu **Zustellungen** gehst und bei einer beliebigen Zustellung auf **Gesendet** schaust.

Header:

| Header | Wert |
| --- | --- |
| X-Asktrix-Event | Der Name des Ereignisses |
| X-Asktrix-Delivery | Die ID der Zustellung. Sie entspricht id im Body und bleibt bei Wiederholungen gleich. |
| X-Asktrix-Signature | t=<Unix-Zeitstempel>,v1=<Signatur> |
| User-Agent | asktrix-webhooks/1 |

Antworte innerhalb von 10 Sekunden mit einem beliebigen `2xx`\-Status. Weiterleitungen werden nicht verfolgt und zählen als Fehler.

## Signatur prüfen

Jeder Webhook hat seinen eigenen **Signatur-Schlüssel** (er beginnt mit `whsec_`). Die Signatur ist ein HMAC-SHA256 in Hex über den Zeitstempel, einen Punkt und den unveränderten Request-Body.

Prüf sie, bevor du der Anfrage vertraust:

1.  Lies `t` und `v1` aus dem Header `X-Asktrix-Signature`.
2.  Lehne die Anfrage ab, wenn `t` mehr als 5 Minuten von deiner Serverzeit abweicht.
3.  Berechne HMAC-SHA256 über `<t>.<roher Body>` mit deinem Schlüssel.
4.  Vergleiche das Ergebnis in konstanter Zeit mit `v1`.

Nimm den Body genau so, wie er angekommen ist. Wenn dein Framework das JSON zuerst parst und du es danach wieder serialisierst, passt die Signatur nicht mehr.

Beispiel für Node.js:

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

export function isValidAsktrixRequest(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.trim().split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const given = String(parts.v1 ?? "");
  return given.length === expected.length && timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}
```

**Neu erzeugen** erstellt einen neuen Schlüssel. Der alte gilt sofort nicht mehr, also hinterleg den neuen direkt danach auf deinem Server.

## Wiederholungen

Schlägt eine Zustellung fehl (Timeout, Verbindungsfehler oder ein Status außerhalb von `2xx`), versuchen wir es nach 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden und 6 Stunden erneut. Das sind insgesamt sechs Versuche. Eine Wiederholung hat dieselbe `id`, du kannst Duplikate also überspringen.

Scheitert dein Endpunkt dauerhaft (20 Fehlversuche in Folge, und eine Zustellung hat alle sechs Versuche aufgebraucht), schalten wir den Webhook ab, und Owner und Admins des Workspace bekommen eine Benachrichtigung. In der Praxis heißt das: stundenlange Fehler, nicht ein kurzer Ausfall. Bring deinen Endpunkt in Ordnung und schalte den Webhook dann mit **Webhook aktiv** wieder ein.

## Zustell-Protokoll

**Zustellungen** zeigt pro Webhook die letzten 30 Tage: Status, Versuche, Dauer, was wir gesendet haben und was dein Server geantwortet hat. Filtere nach **Fehlgeschlagen** und stell mit **Erneut senden** ein einzelnes Ereignis noch einmal zu.

## Grenzen

-   Die Endpunkt-URL muss mit `https://` beginnen und aus dem Internet erreichbar sein. Private und lokale Adressen sind gesperrt.
-   Webhooks feuern nur, solange dein Workspace einen Plan hat, der sie enthält. Nach einem Downgrade bleiben deine Endpunkte erhalten, bekommen aber nichts mehr.

---
Source: https://localhost:3100/help/de/webhooks