Live-Chat Webhooks

Webhooks ermöglichen es onWebChat, Ereignisse in Echtzeit an Ihren Server zu senden. Immer wenn etwas in einem Chat passiert: ein neues Gespräch beginnt, eine Nachricht gesendet wird, ein Chat geschlossen oder bewertet wird, oder eine Offline-Nachricht hinterlassen wird, senden wir einen HTTP POST mit einem JSON-Body an eine URL Ihrer Wahl.

Dies ist der einfachste Weg, Chat-Protokolle in Ihr CRM oder CMS zu synchronisieren, Follow-up-E-Mails auszulösen, benutzerdefinierte Berichte zu erstellen oder ein anderes System zu benachrichtigen, ohne Polling.

Webhooks sind in allen bezahlten Plänen verfügbar. Jede Zustellung ist signiert, damit Sie überprüfen können, dass sie wirklich von onWebChat stammt.



POST https://your-server.com/onwebchat-webhook
Content-Type: application/json
X-OWC-Event: chat.closed
X-OWC-Delivery: 9381
X-OWC-Signature: sha256=4f1c...c2a9

{ "event": "chat.closed", "siteid": 1234, ... }

Webhooks einrichten

Öffnen Sie Ihr Dashboard und gehen Sie zu Einstellungen → Webhooks. Klicken Sie auf "Endpoint hinzufügen", fügen Sie die URL ein, die Ereignisse empfangen soll, wählen Sie die gewünschten Ereignisse (oder wählen Sie "Alle Ereignisse") und speichern Sie.

Beim Erstellen eines Endpoints generieren wir ein Signing-Secret. Sie verwenden dieses Secret, um eingehende Anfragen zu verifizieren (siehe Signaturen verifizieren). Sie können es jederzeit neu generieren.

Sie können mehrere Endpoints pro Website hinzufügen und aktuelle Zustellungen überprüfen, einschließlich HTTP-Status, Anzahl der Versuche und etwaiger Fehler, direkt im Dashboard.



/* Dashboard → Settings → Webhooks */

URL      : https://your-server.com/onwebchat-webhook
Events   : chat.closed, message.created
Secret   : whsec_3f9a...   (used to verify requests)
Status   : Enabled

Ereignistypen

Abonnieren Sie eine beliebige Kombination der folgenden Ereignisse. Jede Nachricht ist mit einem "author" von visitor, agent, ai oder trigger versehen, sodass dasselbe Ereignis message.created Gespräche abdeckt, die von Ihrem Team und vom KI-Chatbot verwaltet werden.

Ereignis	Wird gesendet, wenn
`chat.created`	Ein neues Chat-Gespräch wird von einem Besucher, einem Trigger, dem KI-Chatbot oder einem Agenten gestartet.
`chat.assigned`	Ein Agent übernimmt einen Chat: nimmt ihn an, übernimmt vom KI-Bot oder akzeptiert eine Weiterleitung.
`message.created`	Eine neue Nachricht wird in einem Chat gesendet. Enthält Nachrichten vom Besucher, einem Agenten und dem KI-Chatbot.
`chat.closed`	Ein Chat endet. Der Payload enthält das vollständige Protokoll, Besucherdetails und Labels.
`chat.rated`	Ein Besucher bewertet einen Chat.
`offline_message.created`	Ein Besucher sendet das Offline-/Kontaktformular, während kein Agent verfügbar ist.
`visitor.updated`	Ein Agent aktualisiert Name, E-Mail, Telefon oder Notizen des Besuchers im Dashboard.
`visitor.banned`	Ein Agent blockiert einen Besucher im Dashboard.
`visitor.unbanned`	Ein Agent gibt einen zuvor blockierten Besucher im Dashboard wieder frei.

Payload-Format

Jeder Webhook ist ein JSON-Objekt mit demselben Umschlag: dem Ereignisnamen, Ihrer siteid, einem ISO-8601-Zeitstempel und einem Datenobjekt, dessen Form vom Ereignis abhängt.

Das Beispiel zeigt einen chat.closed-Payload, der das gesamte Gespräch enthält. Kleinere Ereignisse wie message.created oder chat.rated enthalten nur die relevanten Felder.


{
  "event": "chat.closed",
  "siteid": 1234,
  "created_at": "2026-06-22T07:40:52.322Z",
  "data": {
    "chat_id": 1206836,
    "started_at": "22-06-2026 10:40",
    "closed_at": "2026-06-22T07:40:52.322Z",
    "visitor": {
      "name": "Sarah Chen",
      "email": "sarah@example.com",
      "phone": "",
      "country": "United States",
      "os": "Windows 10",
      "browser": "Chrome 149.0"
    },
    "agents": ["Alex"],
    "labels": [{ "name": "sales", "color": "#4caf50" }],
    "messages": [
      { "author": "visitor", "text": "pricing info please", "time": "10:40" },
      { "author": "ai", "text": "Here is a quick overview...", "time": "10:40" }
    ]
  }
}

Signaturen verifizieren

Jede Anfrage enthält einen X-OWC-Signature-Header mit einem HMAC-SHA256-Hash des genauen rohen Anfragekörpers, berechnet mit dem Signing-Secret Ihres Endpoints.

Um eine Anfrage zu verifizieren, berechnen Sie den HMAC-SHA256 des rohen Körpers mit Ihrem Secret und vergleichen Sie ihn mit dem Header-Wert (dem Teil nach "sha256="). Verwenden Sie einen zeitkonstanten Vergleich und hashen Sie immer den rohen Körper.

Sie erhalten auch X-OWC-Event (den Ereignisnamen) und X-OWC-Delivery (eine eindeutige Zustellungs-ID für Idempotenz).


// Node.js / Express
const crypto = require('crypto');

app.post('/onwebchat-webhook',
  express.raw({ type: '*/*' }), (req, res) => {

  const secret = 'whsec_your_secret';
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(req.body)              // raw Buffer
    .digest('hex');

  const got = req.headers['x-owc-signature'] || '';

  // constant-time compare; guard length first (timingSafeEqual throws on mismatch)
  const a = Buffer.from(got), b = Buffer.from(expected);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return res.status(401).end();

  const payload = JSON.parse(req.body.toString());
  // ... handle payload.event ...
  res.sendStatus(200);
});

Verifizierung in PHP

Dieselbe Prüfung in PHP: Lesen Sie den rohen Anfragekörper, berechnen Sie den HMAC mit Ihrem Secret neu und vergleichen Sie mit hash_equals().


<?php
$secret  = 'whsec_your_secret';
$payload = file_get_contents('php://input');
$got     = $_SERVER['HTTP_X_OWC_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);

if (!hash_equals($expected, $got)) {
    http_response_code(401);
    exit;
}

$event = json_decode($payload, true);
// ... handle $event['event'] ...
http_response_code(200);

Wiederholungen & Automatische Deaktivierung

Ihr Endpoint sollte so schnell wie möglich mit einem 2xx-Status antworten. Jede Nicht-2xx-Antwort, ein Timeout oder ein Verbindungsfehler wird als Fehler behandelt.

Fehlgeschlagene Zustellungen werden mit zunehmendem Abstand wiederholt: nach 1 Minute, 5 Minuten, 20 Minuten, 1 Stunde und 2 Stunden.

Wenn ein Endpoint weiterhin fehlschlägt (5 aufeinanderfolgende Fehler), wird er automatisch deaktiviert und der Website-Inhaber wird benachrichtigt. Reaktivieren Sie ihn über das Dashboard. HTTP 410 deaktiviert sofort.



    Attempt 1  → immediately
    Attempt 2  → after  1 minute
    Attempt 3  → after  5 minutes
    Attempt 4  → after 20 minutes
    Attempt 5  → after  1 hour
    Attempt 6  → after  2 hours

    5 failures in a row → endpoint disabled

Best Practices

Verifizieren Sie immer den X-OWC-Signature, bevor Sie einem Payload vertrauen.
Antworten Sie schnell mit 2xx, dann erledigen Sie aufwendige Arbeit asynchron, damit kein Timeout entsteht.
Verwenden Sie X-OWC-Delivery zur Deduplizierung, da dieselbe Zustellung nach einem vorübergehenden Fehler erneut versucht werden kann.
Betreiben Sie Ihren Endpoint über HTTPS.
Ignorieren Sie unbekannte Ereignistypen, damit neue Ereignisse Ihre Integration nicht unterbrechen.

Bereit loszulegen? Pläne ansehen oder öffnen Sie Einstellungen → Webhooks in Ihrem Dashboard.