الإشعارات عبر Webhooks

بدل الاستعلام المتكرر عن الإعلانات الجديدة، اجعلها تصل إليك. اشترك بعنوان HTTPS في الأحداث المطلوبة، مع مرشّحات تحدد الإعلانات المعنية:

curl -X POST "https://api.darak.app/v1/organization/webhooks" \
  -H "Authorization: Bearer $DARAK_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/darak-webhook",
    "event_types": ["listing.created"],
    "filters": { "city": "riyadh", "listing_type": "rent", "beds_min": "3" }
  }'

تُظهر الاستجابة سر التوقيع مرة واحدة. احفظه؛ لا يمكنك قراءته لاحقًا.

يجب أن يستخدم رابطك https:// والمنفذ الافتراضي، وأن يُحل إلى عنوان عام. نفحص ذلك عند التسجيل وقبل كل تسليم، ولا نتبع إعادة التوجيه. إذا انتقل المستقبِل، حدّث الرابط هنا بدل التحويل.

تستخدم المرشّحات مفردات GET /listings نفسها، والمدينة مطلوبة؛ بدونها يصبح الاشتراك لكل إعلان جديد في المملكة، ولا نكتشف حجم التسليم إلا بعد وصوله.

ما يصلك

{
  "id": "evt_9f2c4a1b8e7d6c5b4a3f2e1d",
  "type": "listing.created",
  "created": "2026-09-21T10:00:00.000Z",
  "data": {
    "listing_id": 128647,
    "city": "Riyadh",
    "listing_type": "rent",
    "property_type": "apartment",
    "price_yearly_sar": 60000,
    "url": "https://darak.app/en/listing/128647"
  }
}

الحمولة صغيرة عمدًا: معرّف وما تغيّر وأين تجد البقية. تصبح تفاصيل الإعلان قديمة قبل إعادة محاولة بعد ساعات، وحد التخزين البالغ 30 يومًا ينطبق على ما تحتفظ به. اجلب GET /listings/{id} عند الحاجة للتفاصيل.

الترويسات: Darak-Signature وDarak-Event-Id وDarak-Event-Type وDarak-Delivery-Attempt.

التحقق من التسليم

يمكن لأي شخص إرسال POST إلى رابطك. تحقّق من التوقيع قبل الوثوق بالجسم:

import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(header: string, body: string, secret: string): boolean {
  const parts = new Map(
    header.split(",").map((p) => p.trim().split("=", 2) as [string, string]),
  );
  const t = Number(parts.get("t"));
  const v1 = parts.get("v1");
  if (!v1 || !Number.isFinite(t)) return false;
  // Reject anything older than five minutes: the timestamp is inside what was
  // signed, so this is what stops a captured request being replayed later.
  if (Math.abs(Math.floor(Date.now() / 1000) - t) > 300) return false;

  const expected = createHmac("sha256", secret).update(`${t}.${body}`).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(v1);
  return a.length === b.length && timingSafeEqual(a, b);
}

وقّع الجسم الخام قبل تحليل JSON؛ إعادة تسلسل الكائن لا تعطي توقيعًا مطابقًا.

التسليم والمحاولات والفشل

• مرة واحدة على الأقل. يعاد التسليم إذا انتهت مهلته بعد حفظ عملك. أزل التكرار باستخدام Darak-Event-Id الثابت عبر المحاولات وإعادة التشغيل.
• أجب بـ2xx للقبول. تُعاد محاولة أي نتيجة أخرى، حتى 4xx؛ قد تعني 404 نشرًا جاريًا، لا حدثًا غير مرغوب، وإسقاطه يفقد بيانات لا يمكن طلبها مجددًا.
• ست محاولات خلال نحو ثماني ساعات: بعد دقيقة، ثم خمس دقائق، ثم ثلاثين دقيقة، ثم ساعتين، ثم ست ساعات. أجب سريعًا ونفّذ العمل لاحقًا؛ تنتهي مهلة الاتصال بعد عشر ثوانٍ.
• يعطّل الفشل المتكرر نقطة النهاية. بعد عشرين عملية تسليم تستنفد محاولاتها، نتوقف ونخبرك بدل الاستمرار إلى مستقبِل غائب. تبقى سجلات التسليم؛ أصلح المستقبِل ثم أعد تشغيلها.

الحدود

حتى 500 حدث لكل نقطة نهاية في كل تشغيل. ينتظر الباقي التشغيل التالي بدل إسقاطه، فيلحق الاشتراك المشغول دون فقد أحداث.

تعكس الأحداث ما يستطيع دارك رصده؛ لا يمكن الإبلاغ عن إعلان ظهر واختفى بين عمليتي جمع. تُقرأ المصادر مرتين يوميًا.

تُسلّم الأنواع الثلاثة، ويُتتبّع كل منها منفصلًا. يبدأ الاشتراك في نوع جديد من وقت إنشاء نقطة نهايتك، لا من تقدم الأنواع الأخرى.

لا يُطلق listing.price_changed إلا عندما يتحرك السعر فعليًا. تحديد السعر لأول مرة ليس تغييرًا، ولا توجد له قيمة في previous_price_yearly_sar.

يشمل listing.delisted فقط ما كان يمكن أن تراه. الإعلان المخفي، كنسخة مكررة أو إعلان بلا صور ليس أرضًا، لم ينتج listing.created، فلا ينتج اختفاؤه حدثًا. يشكل ذلك نحو خُمس التعطيلات اليومية.

إدارتها

يسرد GET /organization/webhooks نقاط نهايتك، ويعرض …/deliveries ما أُرسل وما أجاب به خادمك، بما في ذلك أول 500 حرف من الرد. يعيد …/deliveries/{id}/replay تسليمًا بعد إصلاح سبب رفضه. تتطلب كلها مفتاح إدارة (dk_admin_…).