वेबहुक · EasyLiveChat

§ 00वेबहुक क्या हैं

जब EasyLiveChat तरफ कुछ होता है — कोई ग्राहक आपके विजेट में संदेश भेजता है, कोई एजेंट बातचीत बंद करता है, ऑडिट-संबंधित कार्रवाई होती है — हम आपकी हर पंजीकृत URL पर आउटबाउंड HTTPS POST करते हैं। बॉडी JSON है और पूरा इवेंट पेलोड रखती है, ताकि आपका सर्वर पोलिंग के बिना प्रतिक्रिया दे सके।

इसे REST API की दर्पण छवि समझें। API वह है जिससे आपका कोड EasyLiveChat तक पहुँचता है। वेबहुक वह हैं जिनसे EasyLiveChat आपके कोड तक पहुँचता है। अधिकांश इंटीग्रेशन दोनों का उपयोग करते हैं।

हर पंजीकृत एंडपॉइंट का अपना सीक्रेट होता है। हम उस सीक्रेट का उपयोग करके हर अनुरोध बॉडी को HMAC-SHA256 से हस्ताक्षरित करते हैं और हेक्स डाइजेस्ट को x-easylivechat-signature हेडर में भेजते हैं। आपका सर्वर उसी सीक्रेट से HMAC पुनः-गणना करता है और तुलना करता है — मिलान का मतलब अनुरोध वास्तव में हमसे आया, बेमेल का मतलब उसे अस्वीकार करें।

§ 01प्लान उपलब्धता

वेबहुक एंडपॉइंट हर पेड प्लान पर और 14-दिवसीय फ्री ट्रायल के दौरान बनाए जा सकते हैं। प्रति-इवेंट बिलिंग नहीं है — कई एंडपॉइंट्स पर फैन-आउट शामिल है।

audit.event स्ट्रीम केवल Enterprise के लिए है, auditWebhookExport एंटाइटलमेंट से नियंत्रित। message.created और conversation.updated हर उस प्लान पर फायर होते हैं जो API एक्सेस की अनुमति देता है।

§ 02एक एंडपॉइंट कॉन्फ़िगर करें

एक एंडपॉइंट जोड़ें https://app.livechattools.com/settings/webhooks. हम प्रति-एंडपॉइंट एक यादृच्छिक सीक्रेट उत्पन्न करेंगे और उसे केवल एक बार निर्माण पर दिखाएँगे। इसे पासवर्ड की तरह मानें — तुरंत अपने सर्वर के सीक्रेट स्टोर में कॉपी करें।

URL — https:// होना चाहिए और सार्वजनिक IP पर रिज़ॉल्व होना चाहिए। हम लूपबैक, निजी और क्लाउड-मेटाडेटा पते दोनों — निर्माण और डिलीवरी के समय अस्वीकार करते हैं।
इवेंट्स — या तो विशिष्ट इवेंट नाम चुनें या * (सभी इवेंट) की सदस्यता लें। वाइल्डकार्ड प्रोटोटाइप के लिए सुविधाजनक हैं, लेकिन सख्त इवेंट सूचियाँ आपके हैंडलर को समझना आसान बनाती हैं।
सीक्रेट — स्वतः-निर्मित, एक बार दिखाया जाता है। हर डिलीवरी पर हस्ताक्षर के लिए उपयोग किया जाता है। यदि आप इसे खो देते हैं, तो एंडपॉइंट को हटा दें और एक नया बनाएँ — पुनर्प्राप्ति का कोई रास्ता नहीं है।

डिफ़ॉल्ट रूप से सक्रिय। आप उसी पेज से किसी भी समय एंडपॉइंट को रद्द कर सकते हैं — डिलीवरी तुरंत बंद हो जाती है।

§ 03पेलोड का आकार

हर डिलीवरी content-type: application/json के साथ एक POST है। हेडर इवेंट की पहचान करते हैं और हस्ताक्षर ले जाते हैं; बॉडी एनवेलप हमेशा { event, deliveredAt, data } होता है:

POST https://your-server.example.com/webhook
content-type: application/json
user-agent: EasyLiveChat-Webhooks/1.0
x-easylivechat-event: message.created
x-easylivechat-signature: sha256=<hex>

{
  "event": "message.created",
  "deliveredAt": "2026-05-27T08:55:25.841Z",
  "data": {
    "conversationId": "cmp...",
    "message": {
      "id": "cmp...",
      "body": "Hi!",
      "senderType": "CUSTOMER",
      "createdAt": "2026-05-27T08:55:25.840Z"
    }
  }
}

event वही मान है जो x-easylivechat-event हेडर में है। data का आकार इवेंट के अनुसार बदलता है — नीचे का इवेंट कैटलॉग देखें।

§ 04हस्ताक्षर सत्यापित करें

जो भी आपके एंडपॉइंट URL को जानता है वह उस पर कचरा POST कर सकता है। HMAC हस्ताक्षर ही है जिससे आप हमारे अनुरोधों को नकली से अलग पहचानते हैं। अपने सीक्रेट से इसे पुनः-गणना करें और बेमेल पर अनुरोध को अस्वीकार करें।

बॉडी के कच्चे बाइट्स पढ़ें (पहले json.parse न करें — पुनः-सीरियलाइज़ करने से कुंजियाँ पुनर्क्रमित होंगी और हैश टूटेगा)। हस्ताक्षर हेडर से sha256= उपसर्ग हटा दें। HMAC-SHA256(rawBody, secret) की गणना करें और प्राप्त हेक्स के साथ टाइमिंग-सेफ तुलना करें।

`Node.js`

import crypto from 'node:crypto';
import express from 'express';

const SECRET = process.env.WEBHOOK_SECRET;
const app = express();
app.use(express.raw({ type: 'application/json' }));

app.post('/webhook', (req, res) => {
  const received = (req.header('x-easylivechat-signature') || '').replace(/^sha256=/, '');
  const expected = crypto.createHmac('sha256', SECRET).update(req.body).digest('hex');
  const ok =
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received, 'hex'), Buffer.from(expected, 'hex'));
  if (!ok) return res.status(401).send('bad signature');

  const event = JSON.parse(req.body.toString('utf8'));
  // handle event.event, event.data...
  res.status(200).send('ok');
});

`Python (Flask)`

import hmac, hashlib, os
from flask import Flask, request, abort

SECRET = os.environ["WEBHOOK_SECRET"].encode()
app = Flask(__name__)

@app.post("/webhook")
def webhook():
    received = request.headers.get("x-easylivechat-signature", "").removeprefix("sha256=")
    expected = hmac.new(SECRET, request.get_data(), hashlib.sha256).hexdigest()
    if not hmac.compare_digest(received, expected):
        abort(401)
    event = request.get_json()
    # handle event["event"], event["data"]...
    return "ok", 200

`curl (debugging)`

# Recompute the signature locally and compare with the header.
echo -n "$RAW_BODY" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET"

timingSafeEqual / hmac.compare_digest — हमेशा निरंतर-समय तुलना का उपयोग करें ताकि हमलावर सीक्रेट को एक-एक बाइट करके न जाँच सकें।

§ 05इवेंट कैटलॉग

आज प्लेटफ़ॉर्म चार इवेंट प्रकार फायर करता है। हम सुविधाओं के साथ और जोड़ते हैं — आगे की संगतता चाहिए तो * की सदस्यता लें।

इवेंट	फायर होता है जब	डेटा का आकार
message.created	किसी बातचीत पर एक नया संदेश आता है, चाहे किसी ने भी भेजा हो (ग्राहक इनबाउंड, एजेंट आउटबाउंड, REST API भेजना)।	{ conversationId, message }
conversation.updated	किसी बातचीत की स्थिति (OPEN · SNOOZED · CLOSED) या उसका assignedAgentId बदलता है।	{ conversationId, status?, assignedAgentId? }
audit.event	जब भी कोई ऑडिट-लॉग पंक्ति लिखी जाती है — एजेंट लॉगिन, भूमिका बदलाव, इंटीग्रेशन निर्माण, कुंजी रद्द आदि। (Enterprise प्लान।)	{ action, entity, entityId, actorId, metadata }
webhook.test	आप सेटिंग्स → Webhooks में "Test" पर क्लिक करते हैं। बिल्कुल असली इवेंट की तरह हस्ताक्षरित और आकारित।	{ tenantId, test: true }

हर वर्तमान और भविष्य के इवेंट को प्राप्त करने के लिए * की सदस्यता लें। यदि आप अपने हैंडलर को क्या जानना चाहिए, इसे सीमित करना चाहते हैं, तो विशिष्ट नामों की सदस्यता लें।

§ 06इंटीग्रेशन का परीक्षण करें

सेटिंग्स → Webhooks में "Test" बटन आपके एंडपॉइंट पर एक webhook.test इवेंट फायर करता है और अपस्ट्रीम HTTP स्थिति और बीता हुआ समय रिपोर्ट करता है। असली ट्रैफ़िक को निर्देशित करने से पहले अपने हैंडलर को मान्य करने के लिए इसका उपयोग करें।

टेस्ट पेलोड ठीक वही बॉडी एनवेलप, हेडर नाम और HMAC योजना उपयोग करता है जो प्रोडक्शन इवेंट करते हैं — यदि आपका सत्यापन webhook.test के लिए पास होता है, तो वह message.created और बाकी सब के लिए भी पास होगा।

§ 07रिट्राई और टाइमआउट

हम आपके सर्वर को प्रतिक्रिया देने के लिए 10 सेकंड देते हैं। कोई भी गैर-2xx स्थिति या नेटवर्क त्रुटि विफलता है। विफल डिलीवरी 2 सेकंड से शुरू होने वाले एक्सपोनेंशियल बैकऑफ़ के साथ 5 बार तक पुनः-प्रयास होती हैं, इसलिए एक अस्थिर एंडपॉइंट उस इवेंट को छोड़ने से पहले कई मौके पाता है।

हम exactly-once डिलीवरी की गारंटी नहीं देते — नेटवर्क फ्लैपिंग में वही इवेंट दो बार पहुँच सकता है। अपने हैंडलर को idempotent बनाएँ: आंतरिक data.message.id (या उस इवेंट के लिए सार्थक id) पर डीडुप करें।

§ 08सुरक्षा चेकलिस्ट

हमेशा https:// का उपयोग करें — सामान्य http:// एंडपॉइंट निर्माण पर अस्वीकृत होते हैं।
हम निजी, लूपबैक और क्लाउड-मेटाडेटा IPs को निर्माण और डिलीवरी दोनों समय ब्लॉक करते हैं, ताकि गलत-कॉन्फ़िगर्ड DNS रिकॉर्ड का उपयोग आपके नेटवर्क में पिवट करने के लिए न किया जा सके।
हस्ताक्षरों की तुलना टाइमिंग-सेफ बराबर (Node crypto.timingSafeEqual, Python hmac.compare_digest, Go hmac.Equal) से करें।
एंडपॉइंट को हटाकर और उसी URL के साथ नया बनाकर रोटेट करें। अपने सीक्रेट स्टोर को परमाणु रूप से अद्यतन करें।

एक संपादन सुझाएँ