Notifiche Cosmic - avvisi web per l'astrologia

Trasforma l’API di AstroWay da richiesta-risposta a streaming evento. Invece di chiedere al cielo in ciclo, si sottoscrive un URL di tipo evento - e AstroWay invia automaticamente il webhook al momento dell’evento (firmato HMAC-SHA256, con ripetizioni e disconnessione “morti” delle sottoscrizioni).

Quali eventi (live)

Tutti questi eventi sono globali (lo stato del cielo non dipende dai dati natali) - i sottoscrittori ricevono lo stesso payload.

Evento	Registrazione	Quando si attiva
`retrograde-start`	`POST /v1/webhooks/retrograde-start`	un pianeta (Mercurio-Plutone) diventa retrogrado
`retrograde-end`	`POST /v1/webhooks/retrograde-end`	un pianeta esce dalla retrograzione (diventa diretto)
`sign-ingress`	`POST /v1/webhooks/sign-ingress`	un pianeta (Sole + Mercurio-Plutone) entra in un nuovo segno
`void-of-course-start`	`POST /v1/webhooks/void-of-course-start`	inizia il periodo di Luna “senza rotta” (VOC)
`eclipse-alert`	`POST /v1/webhooks/eclipse-alert`	7 giorni prima di un’eclissi solare o lunare

Come sottoscriversi

È necessario una chiave API collegata al tuo account.

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 }

Gestisci le sottoscrizioni: GET /v1/webhooks (elenco), GET /v1/webhooks/{id}, DELETE /v1/webhooks/{id}, POST /v1/webhooks/{id}/test (test del trasporto sul tuo URL).

Cosa arriva sul tuo URL

POST con i header X-AstroWay-Signature: sha256=<hmac>, X-AstroWay-Event, X-AstroWay-Delivery-Id e corpo:

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

Verifica del sigillo

Il sigillo è HMAC-SHA256(signing_secret, raw_body) in esadecimale. Verifica con il header X-AstroWay-Signature (senza prefisso 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));
}

La sottoscrizione si disattiva dopo 5 trasporti consecutivi falliti (non-2xx o timeout di 8 s) - riattivala attraverso GET /v1/webhooks → sospensione/riattivazione cancella il contatore.

Costo

Registrazione e gestione delle sottoscrizioni - Tier 1 (10 crediti) per chiamata, eseguite raramente. Il trasporto dell’evento sul tuo URL non è tassato - non c’è tariffa separata.

Utile?