Webhook Live Chat

I webhook permettono a onWebChat di inviare eventi al tuo server in tempo reale. Ogni volta che succede qualcosa in una chat: inizia una nuova conversazione, viene inviato un messaggio, una chat viene chiusa, valutata o viene lasciato un messaggio offline, inviamo un HTTP POST con un corpo JSON a un URL di tua scelta.

È il modo più semplice per sincronizzare le trascrizioni delle chat nel tuo CRM o CMS, inviare email di follow-up, creare report personalizzati o notificare un altro sistema, senza polling.

I webhook sono disponibili in tutti i piani a pagamento. Ogni consegna è firmata in modo da poter verificare che provenga davvero da 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, ... }

Configurare i Webhook

Apri il tuo pannello e vai su Impostazioni → Webhook. Clicca su "Aggiungi endpoint", incolla l'URL che deve ricevere gli eventi, scegli quali eventi desideri (o seleziona "Tutti gli eventi") e salva.

Quando crei un endpoint generiamo un segreto di firma. Userai questo segreto per verificare le richieste in arrivo (vedi Verifica delle Firme). Puoi rigenerarlo in qualsiasi momento.

Puoi aggiungere più endpoint per sito web e rivedere le consegne recenti, inclusi lo stato HTTP, il numero di tentativi e qualsiasi errore, direttamente nel pannello.



/* Dashboard → Settings → Webhooks */

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

Tipi di Evento

Iscriviti a qualsiasi combinazione degli eventi seguenti. Ogni messaggio è etichettato con un "author" di visitor, agent, ai o trigger, quindi lo stesso evento message.created copre le conversazioni gestite dal tuo team e dal chatbot IA.

Evento	Inviato quando
`chat.created`	Una nuova chat viene avviata da un visitatore, un trigger, il chatbot IA o un agente.
`chat.assigned`	Un agente prende in carico una chat: la prende, subentra al bot IA o accetta un trasferimento.
`message.created`	Un nuovo messaggio viene inviato in una chat. Include messaggi dal visitatore, da un agente e dal chatbot IA.
`chat.closed`	Una chat termina. Il payload include la trascrizione completa, i dettagli del visitatore e le etichette.
`chat.rated`	Un visitatore valuta una chat.
`offline_message.created`	Un visitatore invia il modulo offline mentre non ci sono agenti disponibili.
`visitor.updated`	Un agente aggiorna il nome, l'email, il telefono o le note del visitatore dal pannello.
`visitor.banned`	Un agente blocca un visitatore dal pannello.
`visitor.unbanned`	Un agente sblocca un visitatore precedentemente bloccato dal pannello.

Formato del Payload

Ogni webhook è un oggetto JSON con la stessa busta: il nome dell'evento, il tuo siteid, un timestamp ISO-8601 e un oggetto dati la cui forma dipende dall'evento.

L'esempio mostra un payload chat.closed, che contiene l'intera conversazione. Gli eventi più piccoli come message.created o chat.rated includono solo i campi rilevanti.


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

Verifica delle Firme

Ogni richiesta include un'intestazione X-OWC-Signature contenente un hash HMAC-SHA256 del corpo grezzo esatto della richiesta, calcolato con il segreto di firma del tuo endpoint.

Per verificare una richiesta, calcola il HMAC-SHA256 del corpo grezzo con il tuo segreto e confrontalo con il valore dell'intestazione (la parte dopo "sha256="). Usa un confronto a tempo costante e fa' sempre l'hash del corpo grezzo.

Ricevi anche X-OWC-Event (il nome dell'evento) e X-OWC-Delivery (un id univoco per idempotenza).


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

Verifica in PHP

La stessa verifica in PHP: leggi il corpo grezzo della richiesta, ricalcola il HMAC con il tuo segreto e confronta con 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);

Tentativi & Disabilitazione Automatica

Il tuo endpoint dovrebbe rispondere con uno stato 2xx il più velocemente possibile. Qualsiasi risposta non-2xx, un timeout o un errore di connessione viene trattato come un fallimento.

Le consegne fallite vengono riprovate con ritardo crescente: dopo 1 minuto, 5 minuti, 20 minuti, 1 ora e 2 ore.

Se un endpoint continua a fallire (5 fallimenti consecutivi), viene automaticamente disabilitato e il proprietario del sito viene notificato. Riabilitalo dal pannello. HTTP 410 lo disabilita immediatamente.



    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

Buone Pratiche

Verifica sempre il X-OWC-Signature prima di fidarti di un payload.
Rispondi 2xx velocemente, poi esegui il lavoro pesante in modo asincrono per non andare in timeout.
Usa X-OWC-Delivery per deduplicare, perché la stessa consegna può essere riprovata dopo un fallimento transitorio.
Servi il tuo endpoint su HTTPS.
Ignora i tipi di eventi sconosciuti affinché i nuovi eventi non rompano la tua integrazione.

Pronto per iniziare? Vedi i piani o apri Impostazioni → Webhook nel tuo pannello.