> ## Documentation Index
> Fetch the complete documentation index at: https://developers.huechat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> لتصلك الأحداث إلى خادمك، موقّعة.

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

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

```bash theme={null}
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` |

الجسم:

```json theme={null}
{
  "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
  }
}
```

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

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

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

<CodeGroup>
  ```javascript Node.js theme={null}
  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));
  }
  ```

  ```python Python theme={null}
  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)
  ```

  ```go Go theme={null}
  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))
  }
  ```
</CodeGroup>

احسب 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` و**بلا ترويسة توقيع**. ما زالت تعمل؛ ولأي شيء
جديد استخدم الاشتراكات الموقّعة أعلاه.