وب‌هوک

رویدادها

رویداد	چه وقت
conversation.created	گفتگوی تازه شروع شد
conversation.assigned	گفتگو به اپراتوری سپرده شد
conversation.transferred	گفتگو منتقل شد
conversation.closed	گفتگو بسته شد
message.created	پیام عمومی تازه (یادداشت‌های داخلی هرگز فرستاده نمی‌شوند)
rating.created	کاربر امتیاز داد
visitor.updated	مشخصات کاربر تغییر کرد
visitor.blocked	کاربر مسدود شد
offline_message.created	پیام فرم آفلاین ثبت شد

شکل درخواست

POST /your-endpoint
Content-Type: application/json
X-HiChat-Event: message.created
X-HiChat-Delivery: 7291...
X-HiChat-Signature: t=1760700000,v1=5f2c...

{ "id": "...", "event": "message.created", "siteId": "...", "createdAt": "2026-10-17T10:00:00.000Z", "data": { } }

سرور شما باید در کمتر از ۵ ثانیه با کد 2xx جواب بدهد. ریدایرکت دنبال نمی‌شود و متن پاسخ شما ذخیره نمی‌شود.

بررسی امضا

امضا HMAC-SHA256 رشته t.body با کلید وب‌هوک است. همیشه امضا را بررسی کنید و درخواست‌های قدیمی‌تر از ۵ دقیقه را رد کنید.

Node.js

import { createHmac, timingSafeEqual } from 'node:crypto'

function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')))
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false
  const expected = createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex')
  return timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 ?? ''))
}

PHP

function verify(string $raw, string $header, string $secret): bool {
    parse_str(str_replace(',', '&', $header), $p);
    if (abs(time() - (int) $p['t']) > 300) return false;
    return hash_equals(hash_hmac('sha256', $p['t'] . '.' . $raw, $secret), $p['v1'] ?? '');
}

Python

import hmac, hashlib, time

def verify(raw: bytes, header: str, secret: str) -> bool:
    p = dict(x.split('=', 1) for x in header.split(','))
    if abs(time.time() - int(p['t'])) > 300:
        return False
    expected = hmac.new(secret.encode(), p['t'].encode() + b'.' + raw, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, p.get('v1', ''))

تلاش دوباره

اگر جواب 2xx نگیریم، تا ۲۴ ساعت با فاصله‌های بیشتر دوباره می‌فرستیم. شناسه X-HiChat-Delivery در همه تلاش‌ها یکی است؛ با آن جلوی پردازش تکراری را بگیرید. اگر یک وب‌هوک پشت سر هم خطا بدهد، خودکار غیرفعال می‌شود و در پنل به شما خبر می‌دهیم.