Einführung Webhooks einrichten Ereignistypen Payload-Format Signaturen verifizieren Wiederholungen & Deaktivierung Best Practices

Live-Chat-Webhooks

Mit Webhooks sendet onWebChat Ereignisse in Echtzeit an Ihren eigenen Server. Immer wenn etwas passiert (ein neuer Chat beginnt, eine Nachricht gesendet, ein Chat geschlossen oder bewertet wird oder ein Besucher eine Offline-Nachricht hinterlässt), senden wir einen HTTP-POST mit einem JSON-Body an eine URL Ihrer Wahl.

Das ist der einfachste Weg, Chat-Protokolle mit Ihrem CRM oder CMS zu synchronisieren, Follow-up-E-Mails auszulösen, eigene Berichte zu erstellen oder ein anderes System zu benachrichtigen, ganz ohne Polling.

Webhooks sind in allen kostenpflichtigen Tarifen und während der 14-tägigen kostenlosen Testphase 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
User-Agent: onWebChat-Webhooks/1.0
X-OWC-Event: chat.closed
X-OWC-Delivery: 9381
X-OWC-Signature: sha256=4f1c...c2a9

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

Webhooks einrichten

Melden Sie sich als Administrator in Ihrem Dashboard an und gehen Sie zu Einstellungen → Webhooks. Klicken Sie auf „Endpunkt hinzufügen“, fügen Sie die URL ein, die Ereignisse empfangen soll, wählen Sie die gewünschten Ereignisse (oder „Alle Ereignisse“, das auch später hinzugefügte Ereignisse umfasst) und speichern Sie.

Beim Erstellen eines Endpunkts generieren wir dafür ein Signaturgeheimnis (Signing-Secret, beginnt mit whsec_). Damit verifizieren Sie eingehende Anfragen (siehe „Signaturen verifizieren“ unten). Sie können das Secret jederzeit erneuern; das alte funktioniert dann sofort nicht mehr.

Sie können pro Website mehrere Endpunkte anlegen und die letzten Zustellungen direkt im Dashboard prüfen, einschließlich HTTP-Status, Anzahl der Versuche und etwaiger Fehler.



/* 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 trägt einen „author“: visitor, agent oder ai (sowie trigger für Trigger-Nachrichten im Protokoll von chat.closed), sodass dasselbe Ereignis message.created sowohl Gespräche Ihres Teams als auch des KI-Chatbots abdeckt.

Ereignis	Wird gesendet, wenn
`chat.created`	Ein neuer Chat (Dialog) beginnt. Das Feld source gibt an, wie: visitor, trigger oder agent.
`chat.assigned`	Ein Agent übernimmt einen Chat: Er nimmt ihn an, übernimmt ihn von einem anderen Agenten oder vom KI-Chatbot oder akzeptiert eine Weiterleitung. Das Feld source ist pickup, reassign, ai_takeover oder transfer.
`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 (1 bis 5 Sterne).
`offline_message.created`	Ein Besucher sendet das Offline-/Kontaktformular, während kein Agent verfügbar ist.
`visitor.updated`	Ein Agent aktualisiert im Chat-Dashboard Name, E-Mail-Adresse, Telefonnummer oder Notizen des Besuchers.
`visitor.banned`	Ein Agent blockiert einen Besucher im Chat-Dashboard.
`visitor.unbanned`	Ein Agent gibt einen zuvor blockierten Besucher im Chat-Dashboard wieder frei.

Payload-Format

Jeder Webhook ist ein JSON-Objekt mit derselben Hülle: dem Ereignisnamen, Ihrer siteid, einem ISO-8601-Zeitstempel und einem data-Objekt, dessen Struktur 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": "",
      "notes": "",
      "country_code": "us",
      "country": "United States",
      "os": "Windows 10",
      "browser": "Chrome 149.0"
    },
    "agents": ["Alex"],
    "labels": [{ "name": "sales", "color": "#4caf50" }],
    "messages": [
      { "author": "visitor", "agent_name": "", "text": "pricing info please", "time": "10:40", "date": "22-06-2026" },
      { "author": "ai", "agent_name": "", "text": "Here is a quick overview...", "time": "10:40", "date": "22-06-2026" },
      { "author": "agent", "agent_name": "Alex", "text": "Hi Sarah, I can help with a quote.", "time": "10:41", "date": "22-06-2026" }
    ]
  }
}

Signaturen verifizieren

Jede Anfrage enthält einen X-OWC-Signature-Header mit einem HMAC-SHA256-Hash des exakten rohen Request-Bodys, berechnet mit dem Signing-Secret Ihres Endpunkts.

Um eine Anfrage zu verifizieren, berechnen Sie den HMAC-SHA256 des rohen Request-Bodys 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 Body, nicht eine erneut serialisierte Version.

Außerdem erhalten Sie X-OWC-Event (den Ereignisnamen) und X-OWC-Delivery (eine eindeutige Zustellungs-ID, die bei Wiederholungen gleich bleibt, sodass Sie sie zur Deduplizierung nutzen können). Anfragen werden mit dem User-Agent onWebChat-Webhooks/1.0 gesendet.


// 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 Request-Body, 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 Endpunkt sollte so schnell wie möglich mit einem 2xx-Status antworten, spätestens nach 10 Sekunden. Jede Antwort außerhalb von 2xx, ein Timeout oder ein Verbindungsfehler gilt als fehlgeschlagener Versuch.

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

Schlagen 5 Zustellungen in Folge auch nach allen Wiederholungen fehl, wird der Endpunkt automatisch deaktiviert, und der Kontoinhaber erhält eine E-Mail. Aktivieren Sie ihn im Dashboard wieder, sobald das Problem behoben ist. Eine Antwort mit HTTP 410 (Gone) deaktiviert den Endpunkt 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 failed deliveries in a row → endpoint disabled

Best Practices

Verifizieren Sie immer den X-OWC-Signature-Header, bevor Sie einem Payload vertrauen.
Antworten Sie schnell mit 2xx und erledigen Sie aufwendige Arbeit danach asynchron (über eine Warteschlange), damit kein Timeout entsteht.
Verwenden Sie X-OWC-Delivery zur Deduplizierung, da dieselbe Zustellung nach einem vorübergehenden Fehler erneut versucht werden kann.
Stellen Sie Ihren Endpunkt über HTTPS bereit.
Ignorieren Sie unbekannte Ereignistypen, damit später hinzugefügte neue Ereignisse Ihre Integration nicht beeinträchtigen.

Bereit loszulegen? Tarife ansehen oder öffnen Sie Einstellungen → Webhooks in Ihrem Dashboard.