Webhooks για live chat

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

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

Τα webhooks διατίθενται σε όλα τα πλάνα επί πληρωμή και κατά τη δωρεάν δοκιμή 14 ημερών. Κάθε αποστολή υπογράφεται, ώστε να μπορείτε να επαληθεύετε ότι προήλθε πράγματι από το onWebChat.



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

Συνδεθείτε στον πίνακα ελέγχου ως διαχειριστής και μεταβείτε στις Ρυθμίσεις → Webhooks. Κάντε κλικ στο «Προσθήκη endpoint», επικολλήστε το URL που θα λαμβάνει τα συμβάντα, επιλέξτε ποια συμβάντα θέλετε (ή επιλέξτε «Όλα τα events», που καλύπτει και όσα προσθέσουμε στο μέλλον) και αποθηκεύστε.

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

Μπορείτε να προσθέσετε πολλά endpoints ανά ιστοσελίδα και να ελέγχετε τις πρόσφατες αποστολές, με το HTTP status, τον αριθμό των προσπαθειών και τυχόν σφάλματα, απευθείας στον πίνακα ελέγχου.



/* Dashboard → Settings → Webhooks */

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

Τύποι συμβάντων

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

Συμβάν	Αποστέλλεται όταν
`chat.created`	Ξεκινά μια νέα συνομιλία (dialog). Το πεδίο source δείχνει πώς: visitor, trigger ή agent.
`chat.assigned`	Ένας εκπρόσωπος αναλαμβάνει μια συνομιλία: την παραλαμβάνει, την αναλαμβάνει από άλλον εκπρόσωπο ή από το AI chatbot ή αποδέχεται μια μεταφορά. Το πεδίο source είναι pickup, reassign, ai_takeover ή transfer.
`message.created`	Αποστέλλεται νέο μήνυμα σε μια συνομιλία. Περιλαμβάνει μηνύματα από τον επισκέπτη, από εκπρόσωπο και από το AI chatbot.
`chat.closed`	Μια συνομιλία τελειώνει. Το payload περιλαμβάνει ολόκληρο το κείμενο της συνομιλίας, τα στοιχεία του επισκέπτη και τις ετικέτες.
`chat.rated`	Ένας επισκέπτης αξιολογεί μια συνομιλία (από 1 έως 5 αστέρια).
`offline_message.created`	Ένας επισκέπτης υποβάλλει τη φόρμα εκτός σύνδεσης / επικοινωνίας ενώ δεν υπάρχει διαθέσιμος εκπρόσωπος.
`visitor.updated`	Ένας εκπρόσωπος ενημερώνει το όνομα, το email, το τηλέφωνο ή τις σημειώσεις του επισκέπτη από τον πίνακα ελέγχου.
`visitor.banned`	Ένας εκπρόσωπος αποκλείει έναν επισκέπτη από τον πίνακα ελέγχου.
`visitor.unbanned`	Ένας εκπρόσωπος καταργεί τον αποκλεισμό ενός επισκέπτη από τον πίνακα ελέγχου.

Μορφή payload

Κάθε webhook είναι ένα αντικείμενο JSON με την ίδια δομή (envelope): το όνομα του συμβάντος, το siteid σας, μια χρονοσφραγίδα ISO-8601 και ένα αντικείμενο data, του οποίου η μορφή εξαρτάται από το συμβάν.

Το παράδειγμα δείχνει ένα payload του συμβάντος chat.closed, που περιέχει ολόκληρη τη συνομιλία. Μικρότερα συμβάντα, όπως τα 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": "",
      "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" }
    ]
  }
}

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

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

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

Λαμβάνετε επίσης τις κεφαλίδες X-OWC-Event (το όνομα του συμβάντος) και X-OWC-Delivery (ένα μοναδικό ID αποστολής που παραμένει ίδιο στις επαναλήψεις, ώστε να το χρησιμοποιείτε για αποφυγή διπλής επεξεργασίας). Τα αιτήματα αποστέλλονται με User-Agent onWebChat-Webhooks/1.0.


// 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 με το secret σας και συγκρίνετε με 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 όσο το δυνατόν γρηγορότερα και το αργότερο μέσα σε 10 δευτερόλεπτα. Κάθε απάντηση εκτός 2xx, λήξη χρόνου (timeout) ή σφάλμα σύνδεσης θεωρείται αποτυχημένη προσπάθεια.

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

Αν 5 συνεχόμενες αποστολές αποτύχουν ακόμη και μετά από όλες τις επαναλήψεις τους, το endpoint απενεργοποιείται αυτόματα και ο κάτοχος του λογαριασμού λαμβάνει email. Ενεργοποιήστε το ξανά από τον πίνακα ελέγχου μόλις διορθωθεί το πρόβλημα. Η απάντηση HTTP 410 (Gone) απενεργοποιεί αμέσως το endpoint.



    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

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

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

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