الأحداث والحمولة
تحمل طلبات الويب هوك ترويسات X-Octane-Event وX-Octane-Delivery وX-Octane-Signature ومغلف JSON يحوي كائن المعاملة الكامل.
كل ويب هوك هو طلب POST عبر HTTPS بثلاث ترويسات X-Octane-* ومغلف JSON يكون فيه data.transaction هو الكائن نفسه الذي تعيده واجهة السحب بالضبط. حقل id في المغلف هو معرّف التسليم، وهو ثابت عبر إعادة المحاولات.
الطلب
POST /your/webhook/path HTTP/1.1
Host: erp.example.com
Content-Type: application/json
User-Agent: Octane-Webhooks/1.0
X-Octane-Event: transaction.confirmed
X-Octane-Delivery: 5f0c2e7a-0d3f-5c1a-9b8e-2a4c6d8e0f13
X-Octane-Signature: t=1758358803,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd| الترويسة | الوصف |
|---|---|
X-Octane-Event | نوع الحدث. القيمة نفسها في type بالجسم. |
X-Octane-Delivery | معرّف التسليم. القيمة نفسها في id بالجسم. استخدمه لمنع التكرار. |
X-Octane-Signature | الطابع الزمني وتوقيع HMAC-SHA256 للجسم. راجع التحقق من التوقيع. |
User-Agent | دائمًا Octane-Webhooks/1.0. |
المغلف
{
"id": "5f0c2e7a-0d3f-5c1a-9b8e-2a4c6d8e0f13",
"type": "transaction.confirmed",
"created_at": "2026-09-20T09:00:03Z",
"api_version": "2026-09-01",
"data": {
"transaction": { "...": "see below" }
}
}| الحقل | الوصف |
|---|---|
id | معرّف التسليم. حتمي لمعاملة ومفتاح معينين: تحمل كل إعادة محاولة أو إعادة تسليم للحدث نفسه المعرّف نفسه. خزّنه وتجاهل التكرارات. |
type | transaction.confirmed أو transaction.external أو webhook.test. |
created_at | وقت إنشاء الحدث، ISO 8601 بالتوقيت العالمي. |
api_version | إصدار مخطط الحمولة. حاليًا 2026-09-01. |
data.transaction | كائن المعاملة. مطابق لكائن المعاملة في واجهة السحب. |
أنواع الأحداث
transaction.confirmed
يُرسل عندما تصبح المعاملة CONFIRMED. قيمة data.transaction.status هي CONFIRMED. معاملات الاسترداد مشمولة وتحمل correction_reference_id.
{
"id": "5f0c2e7a-0d3f-5c1a-9b8e-2a4c6d8e0f13",
"type": "transaction.confirmed",
"created_at": "2026-09-20T09:00:03Z",
"api_version": "2026-09-01",
"data": {
"transaction": {
"id": 185432,
"status": "CONFIRMED",
"created_at": "2026-09-20T08:59:36.340Z",
"confirmed_at": "2026-09-20T09:00:02.110Z",
"correction_reference_id": null,
"corporate": { "id": 67, "name": "Acme Logistics" },
"corporate_group": { "id": 9, "name": "Acme Group" },
"fuel": {
"type": { "id": 2, "name": "Benzine 92" },
"liters": 18.5,
"price_per_liter": 13.75,
"amount": 254.38
},
"odometer_reading": 120450,
"distance_traveled": 312,
"fuel_consumption": 5.93,
"station": {
"id": 164,
"name": "Misr Petroleum - Ring Road",
"provider": { "id": 7, "name": "Misr Petroleum" },
"is_external": false
},
"vehicle": {
"id": 4,
"code": "V-004",
"number_plate": "ABC 1234",
"chassis_number": "JTDBR32E720123456",
"brand": "Toyota",
"model": "Hilux",
"year": 2021,
"department": { "id": 3, "name": "Distribution" }
},
"driver": { "id": 31, "name": "Ahmed Mostafa" },
"fees": {
"total_fees": 1.06,
"total_vat": 0.13,
"total_amount": 255.435000
},
"images": {
"pump": "https://storage.example/pump.jpg?X-Amz-Expires=86400&...",
"odometer": "https://storage.example/odometer.jpg?X-Amz-Expires=86400&...",
"expires_at": "2026-09-21T09:00:03Z"
}
}
}
}transaction.external
يُرسل عند تسجيل معاملة EXTERNAL. المغلف وشكل المعاملة نفسهما؛ status هي EXTERNAL، وstation.is_external هي true، وstation.id وstation.provider هما null، وتُرسل fees كما هي مسجلة بالضبط.
webhook.test
يُرسل عند الطلب من أوكتين لتتحقق من الاتصال ومن التحقق من التوقيع. المغلف نفسه وtype هي webhook.test. تحقق من التوقيع وأعد 2xx. لا تعامل data فيه كمعاملة حقيقية.
كيف تختلف الحمولة عن واجهة السحب؟
| الموضوع | واجهة السحب | الويب هوك |
|---|---|---|
| صلاحية روابط الصور | ساعة واحدة | 24 ساعة، تُعاد التوقيع مع كل محاولة تسليم |
| الترتيب | الأحدث أولًا، مرقّم | حدث واحد لكل تسليم، بترتيب تأكيد المعاملات (غير مضمون) |
mobile_number للسائق | فقط عند تفعيله على المفتاح | كذلك |
كل شيء آخر، بما فيه أسماء الحقول وقابليتها للفراغ والدقة، متطابق.
نظرة عامة على الويب هوك
ترسل أوكتين طلب POST موقّعًا عبر HTTPS إلى نقطة النهاية لديك عند تأكيد معاملة أو تسجيل معاملة خارجية. متطلبات نقطة النهاية وأنواع الأحداث.
التحقق من التوقيع
تحقق من X-Octane-Signature بحساب HMAC-SHA256 على الطابع الزمني ونقطة والجسم الخام بسر الويب هوك الخاص بك. أمثلة بلغات Node.js وPython وPHP وC# وJava.


