Cosmic Notifications: webhooks للأحداث الفلكية

Last updated 29 سبتمبر 2026 عرض بصيغة Markdown إعداد الوكيل

حوّل AstroWay API من نموذج طلب-استجابة إلى تدفّق أحداث. بدل استطلاع السماء في حلقة، تشترك بعنوان URL في نوع حدث، ويرسل AstroWay بنفسه webhook لحظة وقوعه (موقّعًا بـ HMAC-SHA256، مع إعادة محاولة تلقائية وتعطيل تلقائي للاشتراكات “الميتة”).

الأحداث المتاحة (live)

كل هذه الأحداث عامة (حالة السماء، لا تعتمد على بيانات الميلاد): يتلقى جميع المشتركين الـ payload نفسه.

الحدث	التسجيل	متى يُطلق
`retrograde-start`	`POST /v1/webhooks/retrograde-start`	كوكب (من عطارد إلى بلوتو) يبدأ التراجع
`retrograde-end`	`POST /v1/webhooks/retrograde-end`	كوكب يخرج من التراجع (يصبح مباشرًا)
`sign-ingress`	`POST /v1/webhooks/sign-ingress`	كوكب (الشمس ومن عطارد إلى بلوتو) يدخل برجًا جديدًا
`void-of-course-start`	`POST /v1/webhooks/void-of-course-start`	تبدأ فترة القمر “الخالي من المسار” (VOC)
`eclipse-alert`	`POST /v1/webhooks/eclipse-alert`	قبل 7 أيام من كسوف الشمس أو خسوف القمر

كيف تشترك

تحتاج إلى مفتاح API مرتبط بحسابك.

curl -X POST https://api.astroway.info/v1/webhooks/retrograde-start \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://your-app.com/hooks/astroway" }'
# { "id": 44, "event": "retrograde-start",
#   "url": "https://your-app.com/hooks/astroway",
#   "signing_secret": "a1b2…",   ← store it; it verifies the signature
#   "active": true }

إدارة الاشتراكات: GET /v1/webhooks (القائمة)، وGET /v1/webhooks/{id}، وDELETE /v1/webhooks/{id}، وPOST /v1/webhooks/{id}/test (تسليم تجريبي إلى عنوان URL الخاص بك).

ما الذي يصل إلى عنوان URL الخاص بك

طلب POST مع الترويسات X-AstroWay-Signature: sha256=<hmac> وX-AstroWay-Event وX-AstroWay-Delivery-Id وبالجسم التالي:

{
  "event": "retrograde-start",
  "delivered_at": "2026-07-15T12:00:00.000Z",
  "subscription_id": 44,
  "data": {
    "planet": "Mercury",
    "station": "retrograde",
    "exactAt": "2026-07-15T11:48:09.967Z",
    "sign": "Leo",
    "longitude": 142.31
  }
}

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

التوقيع هو HMAC-SHA256(signing_secret, raw_body) بصيغة hex. قارنه بالترويسة X-AstroWay-Signature (دون البادئة sha256=):

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

function verify(rawBody, header, secret) {
  const expected = createHmac('sha256', secret).update(rawBody).digest('hex');
  const got = header.replace(/^sha256=/, '');
  return got.length === expected.length &&
    timingSafeEqual(Buffer.from(got), Buffer.from(expected));
}

يُعطَّل الاشتراك تلقائيًا بعد 5 عمليات تسليم فاشلة متتالية (استجابة غير 2xx أو مهلة 8 ثوانٍ). فعّله مجددًا عبر GET /v1/webhooks ← الإيقاف المؤقت ثم الاستئناف يعيد ضبط العدّاد.

السعر

التسجيل وإدارة الاشتراكات: Tier 1 (10 أرصدة) لكل استدعاء، وهي عمليات نادرة. تسليم الحدث إلى عنوان URL الخاص بك غير مدفوع: لا توجد تعرفة منفصلة.