Webhooks

اشترك بعنوان URL في الأحداث التي تهمك. ترسل HueChat جسم JSON لكل حدث وتوقّعه بسر لا يعرفه سواك وHueChat.

إنشاء اشتراك

curl -X POST https://app.huechat.ai/api/v2/accounts/$ACCOUNT_ID/outbound-webhooks \
  -H "Authorization: Bearer $HUECHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "مزامنة CRM",
    "url": "https://your-server.example/webhooks/huechat",
    "events": ["message.created", "conversation.created", "conversation.status_changed", "contact.created", "contact.updated"]
  }'

تحمل الاستجابة قيمة secret مرة واحدة. احفظها بجانب رمزك.

الأحداث

الحدث	يُطلق عندما
`conversation.created`	تبدأ محادثة جديدة
`conversation.updated`	تتغير التصنيفات أو السمات المخصصة
`conversation.status_changed`	مفتوحة، معلّقة، محلولة
`conversation.assigned`	تُعيّن لوكيل أو فريق
`message.created`	تُرسل رسالة أو تُستقبل
`message.updated`	تُعدّل رسالة أو تتغير حالتها
`message.delivered`	تؤكد القناة التسليم
`message.read`	يقرأها المستلم
`message.failed`	يفشل التسليم
`contact.created`	تُضاف جهة اتصال
`contact.updated`	يتغير ملف جهة اتصال
`agent.assigned`	يتولى وكيل محادثة
`agent.available`	يصبح وكيل متصلًا
`automation.triggered`	تُطلق قاعدة أتمتة
`sla.breached`	تُخرق سياسة اتفاقية مستوى خدمة
`webhook.test`	تستدعي نقطة نهاية الاختبار

شكل التسليم

الترويسات:

الترويسة	مثال
`X-HueChat-Signature`	`sha256=a1b2c3…`
`X-HueChat-Event`	`message.created`
`X-HueChat-Delivery`	`12345`
`X-HueChat-Timestamp`	`1712345678`
`User-Agent`	`HueChat-Webhook/2.0`

الجسم:

{
  "event": "message.created",
  "timestamp": "2026-04-05T12:00:00Z",
  "account_id": 3,
  "data": {
    "id": 789,
    "content": "مرحبًا، أحتاج مساعدة في طلبي",
    "message_type": 0,
    "conversation_id": 123,
    "sender": { "id": 456, "name": "أحمد", "type": "contact" },
    "created_at": 1712345678
  }
}

التحقق من التوقيع

تحقق دائمًا من X-HueChat-Signature قبل التصرف بناءً على أي تسليم. أي شخص يعثر على عنوانك يستطيع الإرسال إليه؛ HueChat وحدها تستطيع التوقيع بسرّك.

التوقيع هو sha256= متبوعًا بقيمة HMAC-SHA256 السداسية لجسم الطلب الخام، بمفتاح هو سر الاشتراك.

import crypto from "node:crypto";

export function verify(rawBody, header, secret) {
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return expected.length === header.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(header));
}

import hmac, hashlib

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)

func verify(body []byte, header, secret string) bool {
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write(body)
	expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))
	return hmac.Equal([]byte(expected), []byte(header))
}

احسب HMAC على البايتات الخام، قبل أي تحليل أو إعادة تسلسل لـ JSON.

الاستجابة

أعد 200 خلال ثوانٍ قليلة ونفّذ العمل الفعلي بشكل غير متزامن. أي حالة أخرى تُعد فشلًا ويُعاد إرسالها. بعد 10 إخفاقات متتالية يُوقف الاشتراك؛ أعد تفعيله عبر PATCH بعد أن تتعافى نقطة النهاية لديك. استخدم X-HueChat-Delivery لإسقاط التكرارات، وارفض التسليمات التي يزيد عمر X-HueChat-Timestamp فيها عن بضع دقائق.

الاختبار والفحص والتدوير

الإجراء	الاستدعاء
إرسال حدث `webhook.test`	`POST /api/v2/accounts/{account_id}/outbound-webhooks/{id}/test`
سجل التسليم مع الحالة والاستجابة	`GET /api/v2/accounts/{account_id}/outbound-webhooks/{id}/logs`
سر جديد	`POST /api/v2/accounts/{account_id}/outbound-webhooks/{id}/regenerate-secret`

Webhooks الحساب (v1)

/core/accounts/{account_id}/webhooks هي قائمة الاشتراكات الأقدم التي تستخدمها صفحة الإعدادات ← التكاملات في لوحة التحكم. ترسل كائن حدث مسطّحًا بأسماء أحداث بشرطة سفلية مثل message_created وبلا ترويسة توقيع. ما زالت تعمل؛ ولأي شيء جديد استخدم الاشتراكات الموقّعة أعلاه.

ابدأ هنا

العمل مع الواجهة

التكامل

إنشاء اشتراك

الأحداث

شكل التسليم

التحقق من التوقيع

الاستجابة

الاختبار والفحص والتدوير

Webhooks الحساب (v1)

​إنشاء اشتراك

​الأحداث

​شكل التسليم

​التحقق من التوقيع

​الاستجابة

​الاختبار والفحص والتدوير

​Webhooks الحساب (v1)

إنشاء اشتراك

الأحداث

شكل التسليم

التحقق من التوقيع

الاستجابة

الاختبار والفحص والتدوير

Webhooks الحساب (v1)