Webhooks

Ένα webhook στέλνει αίτημα HTTPS στον διακομιστή σας τη στιγμή που συμβαίνει κάτι στον χώρο εργασίας σας. Χρησιμοποιήστε webhooks αντί για polling του API: όταν τελειώνει μια κλήση, λαμβάνετε τη σύνοψη, το αποτέλεσμα, τα συλλεγμένα στοιχεία και τη μεταγραφή αμέσως. Κάθε παράδοση υπογράφεται με ένα μυστικό που γνωρίζετε μόνο εσείς και το Ringhum, ώστε ο διακομιστής σας να μπορεί να απορρίπτει οτιδήποτε δεν προήλθε από το Ringhum.

Προσθέστε endpoint

Μόνο ο Owner και οι Admins του χώρου εργασίας μπορούν να προσθέτουν, να δοκιμάζουν και να αφαιρούν endpoints.

1. Ανοίξτε Προγραμματιστές στην πλαϊνή μπάρα.
2. Στην κάρτα Webhooks, κάντε κλικ στο Προσθήκη endpoint.
3. Εισαγάγετε το URL endpoint. Πρέπει να ξεκινά με https://.
4. Στο Events, επιλέξτε τα γεγονότα που θέλετε. Το call.ended είναι ήδη επιλεγμένο.
5. Κάντε κλικ στο Προσθήκη endpoint.
6. Αντιγράψτε το μυστικό υπογραφής από το πράσινο πλαίσιο (ξεκινά με whsec_) και αποθηκεύστε το στον διακομιστή σας. Κάντε κλικ στο Ολοκληρώθηκε.

Σημαντικό: Το μυστικό υπογραφής εμφανίζεται μόνο μία φορά. Αν το χάσετε, αφαιρέστε το endpoint και προσθέστε το ξανά για να λάβετε νέο μυστικό.

Μπορείτε να προσθέσετε όσα endpoints χρειάζεστε. Τα webhooks καλύπτουν κάθε βοηθό στον χώρο εργασίας. Μπορείτε επίσης να διαχειρίζεστε endpoints μέσω του API, με POST /webhooks και κλειδί που έχει την εμβέλεια write.

Events

Πώς μοιάζει μια παράδοση

Κάθε παράδοση είναι ένα POST με σώμα JSON και αυτές τις κεφαλίδες:

POST https://example.com/hooks/ringhum
Content-Type: application/json
User-Agent: Ringhum-Webhooks/1.0
X-Ringhum-Event: call.ended
X-Ringhum-Timestamp: 1789250000
X-Ringhum-Signature: v1=5f1a…

{
  "id": "evt_8f2k…",
  "type": "call.ended",
  "created_at": "2026-09-24T14:03:11+00:00",
  "data": {
    "call_id": 4812,
    "direction": "inbound",
    "from": "+14155550132",
    "to": "+14155550100",
    "assistant_id": 3,
    "status": "completed",
    "outcome": "message_taken",
    "sentiment": "neutral",
    "duration_seconds": 94,
    "summary": "Caller asked for a quote for a kitchen repair…",
    "extracted": { "name": "Dana Lee", "reason": "Quote" },
    "transcript": [
      { "role": "assistant", "content": "Hello, you've reached…" },
      { "role": "user", "content": "Hi, I'd like a quote…" }
    ]
  }
}

Το αντικείμενο data εξαρτάται από το γεγονός:

• call.ended και message.taken: τα παραπάνω πεδία κλήσης.
• call.started και call.transferred: call_id, direction, from, to, assistant_id, status και started_at.
• appointment.*: appointment_id, title, status, starts_at, ends_at, timezone, customer (όνομα, τηλέφωνο, email), contact_id, service, staff, call_id και notes.
• order.*: order_id, number, status, fulfillment, customer, address, items με επιλογές και τιμές, currency, subtotal, fee, total, source, call_id και, για ακυρώσεις, cancel_reason.
• reservation.*: reservation_id, number, status, room, check_in, check_out, nights, adults, children, guest, currency, nightly, total και source.
• campaign.completed: campaign_id, name και τα νούμερα προόδου της καμπάνιας.

Σημείωση: Όταν ο βοηθός κλείνει ραντεβού κατά τη διάρκεια κλήσης, μπορεί να λάβετε το appointment.booked δύο φορές. Το ένα αποστέλλεται καθώς γίνεται η κράτηση, με τα πεδία ραντεβού. Το άλλο αποστέλλεται αφού συνοψιστεί η κλήση, με τα πεδία κλήσης. Ελέγξτε αν το data έχει appointment_id ή call_id και χρησιμοποιήστε το πεδίο id για να αποφύγετε την επεξεργασία μιας παράδοσης δύο φορές.

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

Η υπογραφή είναι ένα HMAC-SHA256 της χρονοσφραγίδας, μιας τελείας, και του ακατέργαστου σώματος αιτήματος, με κλειδί το μυστικό υπογραφής του endpoint σας. Αποστέλλεται ως v1= ακολουθούμενο από το hex digest.

1. Διαβάστε το ακατέργαστο σώμα ακριβώς όπως ελήφθη, πριν από οποιαδήποτε ανάλυση JSON.
2. Δημιουργήστε το string {X-Ringhum-Timestamp}.{raw body}.
3. Υπολογίστε το HMAC-SHA256 με το μυστικό σας και προσθέστε το πρόθεμα v1=.
4. Συγκρίνετέ το με το X-Ringhum-Signature χρησιμοποιώντας σύγκριση σταθερού χρόνου.
5. Απορρίψτε το αίτημα αν η χρονοσφραγίδα είναι παλαιότερη από πέντε λεπτά, για να μπλοκάρετε επαναλαμβανόμενα αιτήματα.

Node.js:

const crypto = require('crypto');

function isValid(req, rawBody, secret) {
  const ts = req.header('X-Ringhum-Timestamp');
  const sig = req.header('X-Ringhum-Signature') || '';
  const expected = 'v1=' + crypto.createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;
  return fresh && sig.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

PHP:

$ts = $_SERVER['HTTP_X_RINGHUM_TIMESTAMP'] ?? '';
$sig = $_SERVER['HTTP_X_RINGHUM_SIGNATURE'] ?? '';
$expected = 'v1=' . hash_hmac('sha256', $ts . '.' . file_get_contents('php://input'), $secret);
if (! hash_equals($expected, $sig) || abs(time() - (int) $ts) > 300) {
    http_response_code(400);
    exit;
}

Αποκρίσεις, χρονικά όρια και επαναλήψεις

• Απαντήστε με οποιαδήποτε κατάσταση 2xx για να επιβεβαιώσετε την παράδοση. Κάντε αργή εργασία αφού απαντήσετε.
• Το Ringhum περιμένει έως 10 δευτερόλεπτα για την απόκρισή σας.
• Αν το endpoint σας δεν απαντήσει με 2xx, η παράδοση δοκιμάζεται έως 3 φορές συνολικά: αμέσως, ξανά μετά από περίπου 10 δευτερόλεπτα, και μια τελευταία φορά περίπου 60 δευτερόλεπτα αργότερα. Μετά από αυτό απορρίπτεται.
• Οι παραδόσεις μπορεί να φτάσουν εκτός σειράς. Χρησιμοποιήστε το created_at και τα ids στο data για να τις τακτοποιήσετε.

Ο πίνακας Webhooks δείχνει την τελευταία κατάσταση HTTP κάθε endpoint και πότε στάλθηκε. Ένα αποτυχημένο endpoint παραμένει ενεργό· το Ringhum δεν το απενεργοποιεί για εσάς.

Δοκιμή, παύση και αφαίρεση

• Το Αποστολή δοκιμαστικού στέλνει αμέσως γεγονός test.ping, και ένα μήνυμα δείχνει την κατάσταση HTTP που επέστρεψε το endpoint σας.
• Ο διακόπτης Ενεργό θέτει σε παύση ένα endpoint. Γεγονότα που συμβαίνουν ενώ είναι ανενεργό δεν αποστέλλονται αργότερα.
• Το Αφαίρεση διαγράφει το endpoint και το μυστικό του.

Συχνές ερωτήσεις

Ποια είναι η διαφορά από τις εφαρμογές Zapier, Make και n8n στο Ενσωματώσεις; Εκείνες οι συνδέσεις χρησιμοποιούν τη σελίδα Ενσωματώσεις και τους έξι τύπους γεγονότων της. Το σώμα τους είναι {"event", "workspace", "sent_at", "data"}, και όταν ορίζετε μυστικό η κεφαλίδα υπογραφής είναι X-Ringhum-Signature: sha256=…, ένα HMAC-SHA256 μόνο του σώματος. Τα webhooks για προγραμματιστές, που περιγράφονται εδώ, καλύπτουν περισσότερα γεγονότα και χρησιμοποιούν την υπογραφή v1= με χρονοσφραγίδα. Δείτε Επιλογή τι αποστέλλεται.

Το endpoint μου επιστρέφει 2xx αλλά ο κώδικάς μου δεν βλέπει τίποτα. Ελέγξτε ότι το γεγονός είναι επιλεγμένο για εκείνο το endpoint, ότι το endpoint είναι ενεργό, και ότι το firewall σας επιτρέπει αιτήματα από το διαδίκτυο.

Γιατί αποτυγχάνει ο έλεγχος υπογραφής; Συνηθέστερα το σώμα αναλύθηκε και κωδικοποιήθηκε ξανά πριν το hashing. Κάντε hash τα ακατέργαστα bytes ακριβώς όπως ελήφθησαν.