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

# أحداث Webhook وبياناتها

> سجّل Webhook عبر OTO API، واطّلع على ما يرسله كل نوع من أنواع الأحداث الثلاثة، وتحقق من توقيعات HMAC-SHA256، وابنِ نقطة نهاية يُعتمد عليها.

يقلب Webhook اتجاه عملية الربط. فبدلًا من أن تسأل OTO عمّا حدث كل بضع دقائق، تستضيف أنت عنوان URL وتُبلغك OTO بما يحدث.

## أنواع الأحداث الثلاثة

| النوع | متى يُرسَل؟ | استخدامه |
| - | - | - |
| `orderStatus` | عند تغيّر حالة الطلب: قيد التنفيذ، تم التوصيل، مرتجع، وكل ما بينها. | إبقاء نظامك وعميلك على اطلاع دائم. وهو النوع الافتراضي. |
| `shipmentError` | عند فشل إنشاء شحنة لدى شركة الشحن. | رصد الطلبات التي كانت ستبقى متوقفة دون ذلك. يتضمن رسالة شركة الشحن نفسها. |
| `newOrders` | عند وصول طلب إلى OTO. | تمرير الطلبات إلى نظام WMS آخر. |

> [!TIP]
>
> **اشترك في shipmentError حتى لو لم تشترك في أي شيء آخر**
>
> الحجز الفاشل صامت بطبيعته: الطلب لا يتحرك، ولا يُرسَل أي حدث تغيير حالة لأن شيئًا لم يتغير.
>
> أما البيانات المرسلة (Payload) فتذكر السبب: `errorCode`، ونص رد شركة الشحن في `deliveryCompanyResponse`، وغالبًا ما يكون شيئًا مثل مدينة أو رمز بريدي ناقص. ومثل هذه المشكلات تُحل في ثوانٍ إذا علم بها أحد، وتبقى غير مرئية لأيام إذا لم يعلم بها أحد.

## تسجيل Webhook

`POST /rest/v2/webhook` Starter+

| الحقل | مطلوب | وظيفته |
| - | - | - |
| `url` | نعم | نقطة النهاية الخاصة بك. |
| `method` | نعم | `POST` أو `PUT`. |
| `webhookType` | لا | أحد الأنواع الثلاثة أعلاه. القيمة الافتراضية `orderStatus` و`newOrders`. |
| `secretKey` | لا | المفتاح السري المشترك الذي يُحسب به توقيع البيانات المرسلة. |
| `authorizationKey` | لا | رمز يُرسل مع الطلب حتى تتمكن نقطة النهاية لديك من رفض أي طلب آخر. |
| `timestampFormat` | لا | تنسيق الطابع الزمني الذي تريده، مثل `yyyy-MM-dd HH:mm:ss`. |
| `orderPrefix` | لا | بادئة تُحذف من معرّفات الطلبات قبل الإرسال، إذا كانت معرّفات OTO تحمل بادئة لا يتوقعها نظامك. |

`GET` يعرض اشتراكاتك، و`PUT` يحدّث اشتراكًا باستخدام `id`، و`DELETE` يحذفه. وجميعها على المسار نفسه.

## ما الذي يصلك؟

تحتوي بيانات `orderStatus` على الطلب وحالته الجديدة، وشركة الشحن والسائق إن وُجدا، ورقم التتبع ورابط التتبع، ورابطًا لبوليصة الشحن (AWB)، و`timestamp` بتوقيت **UTC**.

وتحتوي بيانات `shipmentError` على `orderId`، و`errorCode`، و`errorMessage` الصادرة من OTO، والرد الخام من شركة الشحن في `deliveryCompanyResponse`.

وتحتوي بيانات `newOrders` على الطلب كاملًا: العنوان، والمنتجات، والوزن، والمبالغ الإجمالية، وطريقة الدفع، وقناة البيع، والمستودع.

## التحقق من أن الطلب صادر من OTO

تحمل كل بيانات مرسلة حقل `signature`: وهو قيمة **HMAC-SHA256** محسوبة على سلسلة نصية موصولة بنقطتين رأسيتين، ومرمّزة بـ base64، باستخدام `secretKey` الذي سجّلته.

| نوع الحدث | السلسلة الموقّعة |
| - | - |
| `orderStatus` | `orderId:status:timestamp` |
| `shipmentError` | `orderId:errorCode:timestamp` |

> [!WARNING]
>
> **تحقق من التوقيع، وارفض الطوابع الزمنية القديمة**
>
> يستطيع أي شخص يعرف عنوان Webhook الخاص بك الوصول إليه. ودون التحقق، يستطيع أي شخص من هؤلاء أن يُبلغ نظامك بأن طلبًا ما قد تم توصيله.
>
> أعد حساب HMAC على السلسلة الموقّعة وقارنه بمقارنة ثابتة الزمن (Constant-time). ثم تأكد من أن الطابع الزمني حديث: فالتوقيع الصحيح على بيانات قديمة هو إعادة إرسال (Replay)، وأخفّ ما قد يفعله هو تعليم طلب الأمس كـ«تم التوصيل» مرة أخرى.

## بناء نقطة نهاية يُعتمد عليها

* **أجب فورًا.** أعد 200 بمجرد استلام البيانات، ونفّذ المعالجة بعد ذلك. فنقطة النهاية البطيئة تبدو كأنها معطلة.
* **توقّع التكرار.** قد تتكرر الإرسالات. اعتمد على `orderId` مع الحالة والطابع الزمني مفتاحًا، واجعل إعادة المعالجة غير ضارة.
* **توقّع وصولها بغير ترتيب.** توقيتات الشبكة لا تلتزم بتسلسل الحالات لديك. لا تُعد الطلب إلى حالة سابقة أبدًا لأن حدثًا أقدم وصل متأخرًا.
* **سجّل النص الخام قبل تحليله.** عندما يتعطل الربط في الساعة الثانية فجرًا، فإن البيانات التي لم تحتفظ بها هي تحديدًا ما كنت تحتاجه.

## صفحات ذات صلة

* [التوثيق](https://docs.tryoto.com/ar/developers/authentication.md) — الرموز وبيئة التجربة.
* [تحديثات الحالة والتتبع](https://docs.tryoto.com/ar/modules/sales-channels/updates.md) — الأحداث نفسها، لكنها تُرسل إلى قناة بيع.
* [فهرس نقاط النهاية](https://docs.tryoto.com/ar/developers/rest-api-reference.md) — كل ما عدا ذلك.


## Related topics

- [أخطاء واجهة API وحدود الاستخدام](https://docs.tryoto.com/ar/developers/errors-and-rate-limits.md)
- [نظرة عامة على OTO API](https://docs.tryoto.com/ar/developers/overview.md)
- [خدمات الويب هوك للتحديثات الفورية](https://docs.tryoto.com/ar/integrations/webhooks.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.