الويب هوك

الويب هوك رابط على سيرفرك بنبعتله POST أول ما حاجة تحصل في المتجر. تحطه وإنت بتعمل المفتاح، أو بعدين من الـ API العام، أو من الـ API نفسه (تحت).

#بنبعت إيه

POST /your/webhook HTTP/1.1
Content-Type: application/json
X-Elmatajer-Event: order.created
X-Elmatajer-Event-Id: 6f1c0b8e-6b0a-4f9e-9d6c-2a7f2b1b5a10
X-Elmatajer-Signature: sha256=3b6c…

{
  "event": "order.created",
  "event_id": "6f1c0b8e-6b0a-4f9e-9d6c-2a7f2b1b5a10",
  "vendor_id": 5907,
  "created_at": "2026-11-03T18:00:16+02:00",
  "data": {
    "order": { "id": 4904, "order_number": "IOY539", "sub_total": 120, "tax": 0, "discount": 0, "grand_total": 150, "payment_type": 1, "status": 1 },
    "customer": { "id": null, "name": "Mona Adel", "email": "mona@example.com", "phone": "+201012345678" }
  }
}

order.status_changed فيه order_id وorder_number وfrom_status وto_status وcustomer. ولو محتاج منتجات الطلب هاته كامل بـ جيب طلب.

#اتأكد من التوقيع

X-Elmatajer-Signature هو sha256= + HMAC-SHA256 لـ الـ body زي ما وصل بسر الويب هوك بتاع المفتاح. قارن بطريقة ثابتة الوقت؛ وأي حاجة مش مطابقة ارفضها.

$raw = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $raw, $webhookSecret);
if (!hash_equals($expected, $_SERVER['HTTP_X_ELMATAJER_SIGNATURE'] ?? '')) {
    http_response_code(401); exit;
}
$event = json_decode($raw, true);
http_response_code(200);

const crypto = require('crypto');
const expected = 'sha256=' + crypto.createHmac('sha256', webhookSecret).update(rawBody).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.get('X-Elmatajer-Signature') || ''));

#التوصيل وإعادة المحاولة

• رُد بأي 2xx خلال 12 ثانية. غير كده بنعيد بعد 1 و5 و15 و60 و180 دقيقة (لحد 8 محاولات).
• التوصيل مرة على الأقل — استخدم X-Elmatajer-Event-Id عشان تتجاهل التكرار.
• أحداث الطلب الواحد بتوصل بالترتيب.
• الـ API العام ← ابعت حدث تجريبي بيبعت webhook.test عشان تجرّب سيرفرك.

#تحكّم فيه من الـ API

GET https://elmatajer.com/api/v1/vendor/webhooks	رابط المفتاح والأحداث اللي بتوصله
POST https://elmatajer.com/api/v1/vendor/webhooks {"url": "https://…"}	حطه أو غيّره
DELETE https://elmatajer.com/api/v1/vendor/webhooks?url=https://…	شيله

التلاتة محتاجين صلاحية webhooks. والرابط لازم يكون https على سيرفر عام.