Live Chat Webhooks

Τα webhooks επιτρέπουν στο onWebChat να στέλνει events στον server σας σε πραγματικό χρόνο. Κάθε φορά που συμβαίνει κάτι σε ένα chat: ξεκινά νέα συνομιλία, αποστέλλεται μήνυμα, κλείνει chat, αξιολογείται ή αφήνεται offline μήνυμα, στέλνουμε HTTP POST με JSON body σε URL της επιλογής σας.

Αυτός είναι ο ευκολότερος τρόπος να συγχρονίσετε τα chats στο CRM ή CMS σας, να ενεργοποιήσετε follow-up emails, να δημιουργήσετε custom αναφορές ή να ειδοποιήσετε άλλο σύστημα, χωρίς polling.

Τα webhooks διατίθενται σε όλα τα επί πληρωμή πλάνα. Κάθε παράδοση υπογράφεται ώστε να μπορείτε να επαληθεύετε ότι προήλθε από το 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, ... }

Ρύθμιση Webhooks

Ανοίξτε το dashboard σας και μεταβείτε στις Ρυθμίσεις → Webhooks. Κάντε κλικ στο "Προσθήκη endpoint", επικολλήστε το URL που θα λαμβάνει τα events, επιλέξτε ποια events θέλετε (ή επιλέξτε "Όλα τα events") και αποθηκεύστε.

Κατά τη δημιουργία ενός endpoint παράγεται αυτόματα ένα signing secret. Θα χρησιμοποιήσετε αυτό το secret για να επαληθεύετε τα εισερχόμενα αιτήματα (δείτε Επαλήθευση Υπογραφών). Μπορείτε να το αναγεννήσετε ανά πάσα στιγμή.

Μπορείτε να προσθέσετε πολλαπλά endpoints ανά ιστοσελίδα και να ελέγχετε πρόσφατες παραδόσεις, συμπεριλαμβανομένου του HTTP status, αριθμού προσπαθειών και τυχόν σφαλμάτων, απευθείας στο 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

Τύποι Events

Εγγραφείτε σε οποιονδήποτε συνδυασμό από τα παρακάτω events. Κάθε μήνυμα φέρει ετικέτα "author" (visitor, agent, ai ή trigger), ώστε το ίδιο event message.created να καλύπτει συνομιλίες χειρισμένες από την ομάδα και από το AI chatbot.

Event	Αποστέλλεται όταν
`chat.created`	Ξεκινά νέο chat από επισκέπτη, trigger, AI chatbot ή agent.
`chat.assigned`	Ένας agent αναλαμβάνει μια συνομιλία: την παραλαμβάνει, αναλαμβάνει από το AI bot ή αποδέχεται μια μεταφορά.
`message.created`	Αποστέλλεται νέο μήνυμα. Περιλαμβάνει μηνύματα από επισκέπτη, agent και AI chatbot.
`chat.closed`	Ένα chat τελειώνει. Το payload περιλαμβάνει πλήρη μεταγραφή, στοιχεία επισκέπτη και ετικέτες.
`chat.rated`	Ένας επισκέπτης αξιολογεί ένα chat.
`offline_message.created`	Ένας επισκέπτης υποβάλλει τη φόρμα offline ενώ δεν υπάρχει διαθέσιμος agent.
`visitor.updated`	Ένας agent ενημερώνει το όνομα, το email, το τηλέφωνο ή τις σημειώσεις του επισκέπτη από το πίνακα ελέγχου.
`visitor.banned`	Ένας agent αποκλείει έναν επισκέπτη από τον πίνακα ελέγχου.
`visitor.unbanned`	Ένας agent ξεμπλοκάρει έναν επισκέπτη που είχε αποκλειστεί, από τον πίνακα ελέγχου.

Μορφή Payload

Κάθε webhook είναι JSON αντικείμενο με το ίδιο envelope: το όνομα event, το siteid σας, ISO-8601 timestamp και ένα data αντικείμενο που εξαρτάται από το event.

Το παράδειγμα δείχνει ένα payload του event chat.closed, που περιέχει ολόκληρη τη συνομιλία. Μικρότερα events όπως message.created ή chat.rated περιλαμβάνουν μόνο τα σχετικά πεδία.


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

Επαλήθευση Υπογραφών

Κάθε αίτημα περιλαμβάνει κεφαλίδα X-OWC-Signature που περιέχει HMAC-SHA256 hash του raw body αιτήματος, υπολογισμένο με το signing secret του endpoint σας.

Για να επαληθεύσετε ένα αίτημα, υπολογίστε το HMAC-SHA256 του raw body με το secret σας και συγκρίνετε με την τιμή κεφαλίδας (το τμήμα μετά το "sha256="). Χρησιμοποιήστε σύγκριση σταθερού χρόνου και πάντα κάντε hash στο raw body.

Λαμβάνετε επίσης X-OWC-Event (το όνομα event) και X-OWC-Delivery (μοναδικό id παράδοσης).


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

Επαλήθευση σε PHP

Ο ίδιος έλεγχος σε PHP: διαβάστε το raw body, υπολογίστε ξανά το HMAC και συγκρίνετε με 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);

Επαναλήψεις & Αυτόματη Απενεργοποίηση

Το endpoint σας πρέπει να απαντά με status 2xx όσο το δυνατόν γρηγορότερα. Κάθε non-2xx απάντηση, timeout ή σφάλμα σύνδεσης αντιμετωπίζεται ως αποτυχία.

Αποτυχημένες παραδόσεις επαναλαμβάνονται με αυξανόμενες καθυστερήσεις: μετά 1 λεπτό, 5 λεπτά, 20 λεπτά, 1 ώρα και 2 ώρες.

Αν ένα endpoint αποτυγχάνει επανειλημμένα (5 συνεχόμενες αποτυχίες), απενεργοποιείται αυτόματα και ο ιδιοκτήτης του site ειδοποιείται. Επανενεργοποιήστε το από το dashboard. Η επιστροφή HTTP 410 το απενεργοποιεί άμεσα.



    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

Βέλτιστες Πρακτικές

Να επαληθεύετε πάντα το X-OWC-Signature πριν εμπιστευτείτε ένα payload.
Απαντήστε 2xx γρήγορα, μετά κάντε βαριά επεξεργασία ασύγχρονα ώστε να μην λήξει ο χρόνος.
Χρησιμοποιήστε X-OWC-Delivery για αποφυγή διπλοεπεξεργασίας.
Χρησιμοποιήστε HTTPS για το endpoint σας.
Αγνοείτε άγνωστους τύπους events ώστε νέα events να μη σπάσουν την ενσωμάτωσή σας.

Έτοιμοι να ξεκινήσετε; Δείτε τα πλάνα ή ανοίξτε Ρυθμίσεις → Webhooks στο dashboard σας.