EasyLiveChat پەیوەندیت پێوە دەکات
لەو ساتەی شتێک ڕوودەدات.

§ 00Webhooks چین

کاتێک شتێک لە لایەنی EasyLiveChat ڕوودەدات — کڕیارێک پەیامێک لە ویجێتەکەتدا دەنێرێت، ئەجێنتێک گفتوگۆیەک دادەخات، کردارێکی پەیوەندیدار بە پشکنین ڕوودەدات — ئێمە POST ی HTTPS ی دەرچوو دەنێرین بۆ هەموو URL یەک کە تۆ تۆماری کردووە. لاشەکە JSON ە و لۆدی ڕووداوی تەواوی هەیە، بۆ ئەوەی ڕاژەکارەکەت بێ پۆڵکردن کاردانەوە بکات.

وەک ئاوێنەی REST API بیری لێبکەرەوە. API بۆ ئەوەیە کۆدەکەت بگاتە EasyLiveChat. Webhooks بۆ ئەوەیە EasyLiveChat بگاتە کۆدەکەت. زۆربەی یەکگرتنەکان هەردووکیان بەکاردەهێنن.

هەر خاڵە کۆتاییەکی تۆمارکراو نهێنی خۆی هەیە. ئێمە هەموو لاشەی داواکارییەک بە HMAC-SHA256 ی ئەو نهێنییەوە واژۆ دەکەین و digest ی hex لە سەرپەڕەی x-easylivechat-signature دەنێرین. ڕاژەکارەکەت HMAC ەکە دیسان بە هەمان نهێنی هەژمار دەکات و بەراورد دەکات — یەکسانی واتە داواکارییەکە بەڕاستی لە لای ئێمەوە هاتووە، نایەکسانی واتە لای ببە.

§ 01بەردەستی پلان

خاڵە کۆتاییەکانی webhook دەکرێت لە هەموو پلانە پارەدراوەکاندا و لە کاتی تاقیکردنەوەی بەخۆڕایی 14 ڕۆژەدا دروست بکرێن. هیچ پارەدانێک بۆ هەر ڕووداوێک نییە — بڵاوکردنەوە بۆ چەند خاڵێک هاوپێچە.

ستریمی audit.event تەنها بۆ Enterprise ە، بە entitlement ی auditWebhookExport بەرگرتراو. message.created و conversation.updated لە هەموو پلانێکدا کە دەسپێگەیشتنی API ڕێگەی پێ دەدات، دەکوژێن.

§ 02خاڵە کۆتاییەک ڕێکبخە

خاڵە کۆتاییەک زیاد بکە لە https://app.livechattools.com/settings/webhooks. ئێمە نهێنییەکی ڕاندۆم بۆ هەر خاڵە کۆتاییەک دروست دەکەین و تەنها جارێک لە کاتی دروستکردندا پیشانتی دەدەین. وەک وشەی نهێنی هەڵسوکەوتی لەگەڵدا بکە — دەستبەجێ بیگوێزەرەوە بۆ گەنجینەی نهێنی ڕاژەکارەکەت.

• URL — دەبێت https:// بێت و بۆ IP ێکی گشتی شیبکرێتەوە. ناونیشانەکانی loopback، تایبەت، و metadata ی هەور هەردووکیان لە کاتی دروستکردن و گەیاندندا ڕەت دەکەینەوە.
• ڕووداوەکان — یان ناوی ڕووداوە دیاریکراوەکان هەڵبژێرە یان لە * (هەموو ڕووداوەکان) بەشدار بە. wildcardەکان بۆ پرۆتۆتایپ گونجاون، بەڵام لیستی توندتری ڕووداو handlerەکەت ئاسانتر دەکات بۆ تێگەیشتن.
• نهێنی — خۆکار دروستکراو، جارێک پیشاندراوە. بۆ واژۆکردنی هەر گەیاندنێک بەکاردێت. ئەگەر ون بکەیت، خاڵە کۆتاییەکە بسڕەوە و یەکێکی نوێ دروست بکە — هیچ ڕێگەیەکی گەڕاندنەوە نییە.

بە بنەڕەت چالاکە. لە هەر کاتێکدا دەتوانیت لە هەمان پەڕە خاڵە کۆتاییەک ڕەت بکەیتەوە — گەیاندنەکان دەستبەجێ دەوەستن.

§ 03شێوەی payload

هەر گەیاندنێک POSTێکە بە content-type: application/json. سەرپەڕەکان ڕووداوەکە دیاری دەکەن و واژۆکە دەگرن؛ زەرفی لاشە هەمیشە { 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 مەکە — دیسان سێریالایز کردن کلیلەکان ڕیز دەکات و hash ەکە دەشکێنێت). پێشگری sha256= لە سەرپەڕەی واژۆ لاببە. HMAC-SHA256(rawBody, secret) هەژمار بکە و بە شێوەیەکی timing-safe لەگەڵ هێگزی وەرگیراو بەراورد بکە.

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کاتالۆگی ڕووداوەکان

ئەمڕۆ سەکۆکە چوار جۆر ڕووداو دەکوژێنێت. کاتێک تایبەتمەندیە نوێیەکان دێن زیادی دەکەین — لە * بەشدار بە ئەگەر دەتەوێت بەرەو پێشەوە گونجاو بێت.

لە * بەشدار بە بۆ وەرگرتنی هەموو ڕووداوێکی ئێستا و داهاتوو. لە ناوی دیاریکراو بەشدار بە ئەگەر دەتەوێت سنووری ئەوەی handlerەکەت پێویستە بزانێت.

§ 06یەکگرتنەکە تاقی بکەرەوە

دوگمەی "Test" لە ڕێکخستن ← Webhooks ڕووداوی webhook.test بۆ خاڵە کۆتاییەکەت دەکوژێنێت و دۆخی HTTP و کاتی ڕۆیشتوو ڕاپۆرت دەکات. ئەمە بەکار بهێنە بۆ ڕاستکردنەوەی handlerەکەت پێش ئەوەی ترافیکی ڕاستەقینەی بۆ ئاراستە بکەیت.

لۆدی تاقیکردنەوە هەمان زەرفی لاشە، ناوەکانی سەرپەڕە، و سکیمی HMAC وەک ڕووداوەکانی بەرهەمهێنان بەکاردەهێنێت — ئەگەر پشکنینەکەت بۆ webhook.test سەرکەوت، بۆ message.created و هەموو شتێکی تریش سەردەکەوێت.

§ 07دووبارەکردنەوە و ماوەی کۆتایی

10 چرکە بە ڕاژەکارەکەت دەدەین بۆ وەڵامدانەوە. هەر دۆخێکی نا-2xx یان هەڵەی تۆڕ شکستە. گەیاندنە شکستخواردووەکان تا 5 جار دیسان هەوڵدەدرێن بە backoff ی ئێکسپۆنێنشاڵ کە لە 2 چرکەوە دەست پێدەکات، بۆیە خاڵە کۆتاییەکی نائارام چەند هەلێکی هەیە پێش ئەوەی واز لەو ڕووداوە بهێنین.

ئێمە مەرجی exactly-once گەیاندن دەستەبەر ناکەین — لە کاتی flapping ی تۆڕدا هەمان ڕووداو دەتوانێت دوو جار بگات. handlerەکەت بکە idempotent: لەسەر data.message.id ی ناوەکی (یان هەر idێک کە بۆ ئەو ڕووداوە بەسوود بێت) دەدووپلیک بکە.

§ 08لیستی پشکنینی پاراستن

• هەمیشە https:// بەکار بهێنە — خاڵە کۆتاییەکانی http:// ی ساکار لە کاتی دروستکردندا ڕەت دەکرێنەوە.
• ئێمە IP ە تایبەت، loopback، و metadata ی هەور لە هەردوو کاتی دروستکردن و گەیاندندا بلۆک دەکەین، بۆیە تۆمارێکی DNS ی هەڵە ڕێکنەخراو ناتوانرێت بەکاربهێنرێت بۆ pivot کردن لە ناو تۆڕەکەتدا.
• واژۆکان بە یەکسانییەکی timing-safe بەراورد بکە (Node crypto.timingSafeEqual، Python hmac.compare_digest، Go hmac.Equal).
• بە سڕینەوەی خاڵە کۆتاییەکە و دروستکردنی یەکێکی نوێ بە هەمان URL بیگەڕێنە. گەنجینەی نهێنیەکەت بە شێوەی ئەتۆمی نوێ بکەرەوە.