Webhooki Czatu na Żywo

Webhooki umożliwiają onWebChat wysyłanie zdarzeń do Twojego serwera w czasie rzeczywistym. Za każdym razem, gdy dzieje się coś w czacie: rozpoczyna się nowa rozmowa, wysyłana jest wiadomość, czat jest zamknięty, oceniony lub pozostawiona jest wiadomość offline, wysyłamy HTTP POST z ciałem JSON na wybrany przez Ciebie URL.

To najłatwiejszy sposób na synchronizację transkrypcji czatów z CRM lub CMS, wyzwalanie e-maili follow-up, tworzenie raportów lub powiadamianie innego systemu, bez pollingu.

Webhooki są dostępne we wszystkich płatnych planach. Każde dostarczenie jest podpisane, dzięki czemu możesz zweryfikować, że naprawdę pochodzi z onWebChat.



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, ... }

Konfiguracja Webhooków

Otwórz panel i przejdź do Ustawienia → Webhooki. Kliknij "Dodaj endpoint", wklej URL, który ma odbierać zdarzenia, wybierz zdarzenia (lub "Wszystkie zdarzenia") i zapisz.

Podczas tworzenia endpointu generujemy sekret podpisywania. Użyjesz go do weryfikacji przychodzących żądań (patrz Weryfikacja Podpisów). Możesz go wygenerować ponownie w dowolnym momencie.

Możesz dodać wiele endpointów na stronę i przeglądać ostatnie dostarczenia, w tym status HTTP, liczbę prób i ewentualne błędy, bezpośrednio w panelu.



/* Dashboard → Settings → Webhooks */

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

Typy Zdarzeń

Subskrybuj dowolną kombinację poniższych zdarzeń. Każda wiadomość ma etykietę "author" visitor, agent, ai lub trigger, więc to samo zdarzenie message.created obejmuje rozmowy obsługiwane przez Twój zespół i przez chatbota AI.

Zdarzenie	Wysyłane gdy
`chat.created`	Nowy czat zostaje uruchomiony przez odwiedzającego, trigger, chatbota AI lub agenta.
`chat.assigned`	Agent przejmuje czat: odbiera go, przejmuje od bota AI lub akceptuje przekazanie.
`message.created`	Nowa wiadomość jest wysyłana w czacie. Obejmuje wiadomości od odwiedzającego, agenta i chatbota AI.
`chat.closed`	Czat się kończy. Payload zawiera pełną transkrypcję, dane odwiedzającego i etykiety.
`chat.rated`	Odwiedzający ocenia czat.
`offline_message.created`	Odwiedzający wysyła formularz offline gdy brak dostępnych agentów.
`visitor.updated`	Agent aktualizuje imię, email, telefon lub notatki odwiedzającego w panelu.
`visitor.banned`	Agent blokuje odwiedzającego z panelu.
`visitor.unbanned`	Agent odblokowuje wcześniej zablokowanego odwiedzającego z panelu.

Format Payload

Każdy webhook to obiekt JSON z tą samą kopertą: nazwa zdarzenia, Twoje siteid, znacznik czasu ISO-8601 i obiekt danych, którego kształt zależy od zdarzenia.

Przykład pokazuje payload chat.closed zawierający całą rozmowę. Mniejsze zdarzenia jak message.created lub chat.rated zawierają tylko odpowiednie pola.


{
  "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" }
    ]
  }
}

Weryfikacja Podpisów

Każde żądanie zawiera nagłówek X-OWC-Signature z hashem HMAC-SHA256 dokładnego surowego ciała żądania, obliczonym za pomocą sekretu podpisywania Twojego endpointu.

Aby zweryfikować żądanie, oblicz HMAC-SHA256 surowego ciała używając swojego sekretu i porównaj z wartością nagłówka (część po "sha256="). Używaj porównania o stałym czasie i zawsze hashuj surowe ciało.

Otrzymujesz też X-OWC-Event (nazwę zdarzenia) i X-OWC-Delivery (unikalny id dostarczenia dla idempotencji).


// 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);
});

Weryfikacja w PHP

Ta sama weryfikacja w PHP: odczytaj surowe ciało żądania, ponownie oblicz HMAC swoim sekretem i porównaj z 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);

Ponowienia & Automatyczne Wyłączanie

Twój endpoint powinien odpowiedzieć statusem 2xx jak najszybciej. Każda odpowiedź non-2xx, timeout lub błąd połączenia jest traktowany jako niepowodzenie.

Nieudane dostarczenia są ponawiane z rosnącym opóźnieniem: po 1 minucie, 5 minutach, 20 minutach, 1 godzinie i 2 godzinach.

Jeśli endpoint nadal zawodzi (5 kolejnych błędów), zostaje automatycznie wyłączony i właściciel witryny jest powiadamiany. Włącz go ponownie z panelu. HTTP 410 wyłącza natychmiast.



    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

Dobre Praktyki

Zawsze weryfikuj X-OWC-Signature przed zaufaniem payloadowi.
Odpowiadaj 2xx szybko, a ciężką pracę wykonuj asynchronicznie aby nie przekroczyć limitu czasu.
Używaj X-OWC-Delivery do deduplikacji, ponieważ to samo dostarczenie może być ponowione po przejściowym błędzie.
Udostępniaj endpoint przez HTTPS.
Ignoruj nieznane typy zdarzeń, aby nowe zdarzenia nie zepsuły Twojej integracji.

Gotowy do startu? Zobacz plany lub otwórz Ustawienia → Webhooki w swoim panelu.