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ایونٹ کیٹلاگ

آج پلیٹ فارم چار ایونٹ اقسام فائر کرتا ہے۔ ہم فیچرز کے ساتھ مزید شامل کرتے ہیں — آگے کی مطابقت چاہیے تو * کو سبسکرائب کریں۔

ہر موجودہ اور مستقبل کے ایونٹ کو وصول کرنے کے لیے * کو سبسکرائب کریں۔ اگر آپ اپنے ہینڈلر کو جو جاننا ہے اسے محدود کرنا چاہتے ہیں تو مخصوص ناموں کو سبسکرائب کریں۔

§ 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 کے ساتھ نیا بنا کر روٹیٹ کریں۔ اپنے سیکریٹ اسٹور کو اٹامک طریقے سے اپ ڈیٹ کریں۔