Cosmic Notifications: webhook sugli eventi astrologici

Trasforma AstroWay API da request-response in uno stream di eventi. Invece di interrogare il cielo in un ciclo, iscrivi un URL a un tipo di evento, e AstroWay invia da solo un webhook nel momento in cui l’evento si verifica (firmato con HMAC-SHA256, con retry automatici e disattivazione automatica delle iscrizioni “morte”).

Quali eventi (live)

Tutti questi eventi sono globali (lo stato del cielo, non dipende dai dati natali): tutti gli iscritti ricevono lo stesso payload.

Evento	Registrazione	Quando scatta
retrograde-start	POST /v1/webhooks/retrograde-start	un pianeta (da Mercurio a Plutone) diventa retrogrado
retrograde-end	POST /v1/webhooks/retrograde-end	un pianeta esce dalla retrogradazione (torna diretto)
sign-ingress	POST /v1/webhooks/sign-ingress	un pianeta (il Sole + da Mercurio a Plutone) entra in un nuovo segno
void-of-course-start	POST /v1/webhooks/void-of-course-start	inizia un periodo di Luna “fuori corso” (VOC)
eclipse-alert	POST /v1/webhooks/eclipse-alert	7 giorni prima di un’eclissi solare o lunare

Nota

Gli eventi legati alla carta natale (transit-trigger, return-due, dasha-change, mahadasha-end) e l’evento basato sulla posizione planetary-hour-tick richiedono i dati natali o le coordinate dell’iscritto e verranno attivati nella prossima fase.

Come iscriversi

Serve 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…",   ← store it; it verifies the signature
#   "active": true }

Gestione delle iscrizioni: GET /v1/webhooks (elenco), GET /v1/webhooks/{id}, DELETE /v1/webhooks/{id}, POST /v1/webhooks/{id}/test (consegna di prova al tuo URL).

Cosa arriva al tuo URL

Una POST con gli header X-AstroWay-Signature: sha256=<hmac>, X-AstroWay-Event, X-AstroWay-Delivery-Id e questo body:

{
  "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 della firma

La firma è HMAC-SHA256(signing_secret, raw_body) in esadecimale. Confrontala con l’header X-AstroWay-Signature (senza il 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));
}

Un’iscrizione viene disattivata automaticamente dopo 5 consegne fallite consecutive (risposta non 2xx o timeout di 8 s). Riattivala tramite GET /v1/webhooks → mettere in pausa e riprendere azzera il contatore.

Prezzo

Registrazione e gestione delle iscrizioni costano Tier 1 (10 crediti) per chiamata, e si eseguono di rado. La consegna dell’evento al tuo URL non viene addebitata: non esiste una tariffa separata.