Cosmic Notifications - webhooks σε αστρολογικά γεγονότα

Μετατρέψτε το AstroWay API από request-response σε event stream. Αντί να ερωτάτε τον ουρανό σε βρόχο, εσύ εγγράφεις ένα URL σε τύπο γεγονότος - και το AstroWay στέλνει αυτόματα webhook τη στιγμή που συμβαίνει (υπογεγραμμένο με HMAC-SHA256, με αυτόματες επαναλήψεις και αυτόματη απενεργοποίηση των «νεκρών» συνδρομών).

Ποια γεγονότα (live)

Όλα αυτά τα γεγονότα είναι παγκόσμια (η κατάσταση του ουρανού δεν εξαρτάται από τα natal δεδομένα) - οι συνδρομητές λαμβάνουν το ίδιο 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 ημέρες πριν από ηλιακή ή σεληνιακή έκλειψη

Σημείωση

Τα natal-εξαρτώμενα γεγονότα - transit-trigger, return-due, dasha-change, mahadasha-end - και το γεγονός τοποθεσίας planetary-hour-tick απαιτούν natal δεδομένα / συντεταγμένες του συνδρομητή και θα ενεργοποιηθούν στην επόμενη φάση.

Πώς να εγγραφείς

Χρειάζεται ένα 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…",   ← збережіть, ним перевіряється підпис
#   "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 ή timeout 8 s) - ενεργοποίησέ τη ξανά μέσω GET /v1/webhooks → η παύση/επαναφορά μηδενίζει τον μετρητή.

Τιμή

Η εγγραφή και η διαχείριση των συνδρομών - Tier 1 (10 credits) ανά κλήση, γίνονται σπάνια. Η αποστολή του γεγονότος στο URL σου δεν χρεώνεται - δεν υπάρχει ξεχωριστή τιμολόγηση.