Ereignisse per Webhook empfangen

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:

{
  "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:

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.