Cosmic Notifications - webhook-uri pentru evenimente astrologice

Transformă AstroWay API din request-response într-un flux de evenimente. În loc să interoghezi cerul într-o buclă, abonezi un URL la un tip de eveniment, iar AstroWay trimite singur un webhook în momentul în care acesta se produce (semnat HMAC-SHA256, cu reîncercări automate și dezactivarea automată a abonamentelor “moarte”).

Ce evenimente există (live)

Toate aceste evenimente sunt globale (starea cerului, nu depind de datele natale): abonații primesc același payload.

Eveniment	Înregistrare	Când se declanșează
retrograde-start	POST /v1/webhooks/retrograde-start	o planetă (Mercur–Pluto) devine retrogradă
retrograde-end	POST /v1/webhooks/retrograde-end	o planetă iese din retrogradare (devine directă)
sign-ingress	POST /v1/webhooks/sign-ingress	o planetă (Soarele + Mercur–Pluto) intră într-un semn nou
void-of-course-start	POST /v1/webhooks/void-of-course-start	începe perioada Lunii “fără curs” (VOC)
eclipse-alert	POST /v1/webhooks/eclipse-alert	cu 7 zile înainte de o eclipsă de Soare sau de Lună

Mențiune

Evenimentele dependente de datele natale, transit-trigger, return-due, dasha-change, mahadasha-end, și evenimentul dependent de locație planetary-hour-tick au nevoie de datele natale / coordonatele abonatului și vor fi activate în faza următoare.

Cum te abonezi

Ai nevoie de o cheie API legată de contul tău.

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 }

Gestionarea abonamentelor: GET /v1/webhooks (listă), GET /v1/webhooks/{id}, DELETE /v1/webhooks/{id}, POST /v1/webhooks/{id}/test (livrare de test către URL-ul tău).

Ce ajunge la URL-ul tău

Un POST cu header-ele X-AstroWay-Signature: sha256=<hmac>, X-AstroWay-Event, X-AstroWay-Delivery-Id și corpul:

{
  "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
  }
}

Verificarea semnăturii

Semnătura este HMAC-SHA256(signing_secret, raw_body) în hex. Compar-o cu header-ul X-AstroWay-Signature (fără prefixul 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));
}

Abonamentul se dezactivează automat după 5 livrări eșuate la rând (non-2xx sau timeout de 8 s); reactivează-l prin GET /v1/webhooks → pauza/reluarea resetează contorul.

Preț

Înregistrarea și gestionarea abonamentelor costă Tier 1 (10 credite) pe apel și se fac rar. Livrarea evenimentului către URL-ul tău nu se taxează: nu există un tarif separat.