EasyLiveChat sizi arar
bir şey olduğu anda.

§ 00Webhook'lar nedir

EasyLiveChat tarafında bir şey olduğunda — bir müşteri widget'ınıza yazdığında, bir temsilci bir konuşmayı kapattığında, denetimle ilgili bir eylem gerçekleştiğinde — kaydettiğiniz her URL'ye giden bir HTTPS POST yaparız. Gövde JSON'dur ve tam olay yükünü içerir; böylece sunucunuz sorgulamadan tepki verebilir.

Bunu REST API'nin ayna görüntüsü olarak düşünün. API, sizin kontrolünüzdeki kodun EasyLiveChat'e uzanmasını sağlar. Webhook'lar EasyLiveChat'in kontrolünüzdeki koda uzanmasını sağlar. Çoğu entegrasyon her ikisini de kullanır.

Kaydedilen her uç noktanın kendi gizli anahtarı vardır. Her istek gövdesini bu gizli anahtarla HMAC-SHA256 kullanarak imzalar ve hex özetini x-easylivechat-signature başlığında göndeririz. Sunucunuz aynı gizli anahtarla HMAC'ı yeniden hesaplar ve karşılaştırır — eşleşme isteğin gerçekten bizden geldiği anlamına gelir, uyuşmama ise reddetmek anlamına gelir.

§ 01Plan kullanılabilirliği

Webhook uç noktaları her ücretli planda ve 14 günlük ücretsiz denemede oluşturulabilir. Olay başına ücretlendirme yoktur — birden çok uç noktaya dağıtım dahildir.

audit.event akışı yalnızca Enterprise içindir, auditWebhookExport yetkilendirmesiyle kontrol edilir. message.created ve conversation.updated, API erişimine izin veren her planda tetiklenir.

§ 02Bir uç nokta yapılandır

Şuradan bir uç nokta ekleyin: https://app.livechattools.com/settings/webhooks. Her uç nokta için rastgele bir gizli anahtar üretir ve oluşturma sırasında size yalnızca bir kez gösteririz. Bir parola gibi davranın — hemen sunucunuzun gizli anahtar deposuna kopyalayın.

• URL — https:// olmalı ve genel bir IP'ye çözümlenmelidir. Loopback, özel ve bulut meta veri adreslerini hem oluşturma hem teslimat sırasında reddediyoruz.
• Olaylar — Belirli olay adlarını seçin veya * (tüm olaylar) için abone olun. Joker karakterler prototipleme için kullanışlıdır ancak daha dar olay listeleri handler'ınız üzerinde düşünmeyi kolaylaştırır.
• Gizli anahtar — Otomatik oluşturulur, bir kez gösterilir. Her teslimatı imzalamak için kullanılır. Kaybederseniz uç noktayı silip yenisini oluşturun — kurtarma yolu yoktur.

Varsayılan olarak etkindir. Aynı sayfadan istediğiniz zaman bir uç noktayı iptal edebilirsiniz — teslimatlar anında durur.

§ 03Payload biçimi

Her teslimat content-type: application/json olan bir POST'tur. Başlıklar olayı tanımlar ve imzayı taşır; gövde zarfı her zaman { event, deliveredAt, data } biçimindedir:

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 başlığıyla aynı değerdir. data biçimi olaya göre değişir — aşağıdaki olay kataloğuna bakın.

§ 04İmzayı doğrula

Uç nokta URL'nizi bilen herkes oraya çöp POST'layabilir. HMAC imzası, gerçek isteklerimizi sahtelerden ayırma yönteminizdir. Gizli anahtarınızla yeniden hesaplayın ve uyuşmazlıkta isteği reddedin.

Ham gövde baytlarını okuyun (önce json.parse YAPMAYIN — yeniden serileştirme anahtarları yeniden sıralar ve hash'i bozar). İmza başlığındaki sha256= önekini kaldırın. HMAC-SHA256(rawBody, secret) hesaplayın ve alınan hex ile zaman-güvenli karşılaştırın.

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 — saldırganların gizli anahtarı bayt bayt yoklayamaması için her zaman sabit zamanlı karşılaştırma kullanın.

§ 05Olay kataloğu

Bugün platform dört tür olayı tetikler. Yeni özellikler geldikçe daha fazlasını ekleriz — ileri uyumluluk istiyorsanız *'a abone olun.

Mevcut ve gelecekteki tüm olayları almak için *'a abone olun. Handler'ınızın bilmesi gerekenleri kısıtlamak istiyorsanız belirli adlara abone olun.

§ 06Entegrasyonu test et

Ayarlar → Webhook'lar bölümündeki "Test" düğmesi, uç noktanıza bir webhook.test olayı tetikler ve üst akış HTTP durumu ile geçen süreyi raporlar. Gerçek trafiği yönlendirmeden önce handler'ınızı doğrulamak için kullanın.

Test yükü, üretim olaylarıyla tam olarak aynı gövde zarfını, başlık adlarını ve HMAC şemasını kullanır — doğrulamanız webhook.test için geçtiyse message.created ve diğer her şey için de geçer.

§ 07Yeniden denemeler ve zaman aşımları

Sunucunuza yanıt vermek için 10 saniye veririz. 2xx olmayan herhangi bir durum veya ağ hatası başarısızlıktır. Başarısız teslimatlar 2 saniyeden başlayan üstel geri çekilmeyle 5 kez yeniden denenir, böylece kararsız bir uç noktanın o olaydan vazgeçmeden önce birkaç şansı olur.

Tam olarak bir kez teslimat GARANTİ ETMİYORUZ — ağ kararsızlığında aynı olay iki kez gelebilir. Handler'ınızı idempotent yapın: iç data.message.id (veya o olay için anlamlı olan id) üzerinden tekilleştirin.

§ 08Güvenlik kontrol listesi

• Her zaman https:// kullanın — düz http:// uç noktaları oluşturmada reddedilir.
• Özel, loopback ve bulut meta veri IP'lerini hem oluşturma hem teslimatta engelleriz; böylece yanlış yapılandırılmış bir DNS kaydı ağınıza pivot yapmak için kullanılamaz.
• İmzaları zaman-güvenli eşitlikle karşılaştırın (Node crypto.timingSafeEqual, Python hmac.compare_digest, Go hmac.Equal).
• Uç noktayı silip aynı URL ile yenisini oluşturarak döndürün. Gizli anahtar deponuzu atomik şekilde güncelleyin.