Cosmic Notifications - webhooks para eventos astrológicos

Convierte AstroWay API de request-response en un flujo de eventos. En lugar de consultar el cielo en un bucle, suscribes una URL a un tipo de evento y AstroWay envía el webhook en el momento en que ocurre (firmado con HMAC-SHA256, con reintentos automáticos y desactivación automática de suscripciones “muertas”).

Qué eventos (live)

Todos estos eventos son globales (el estado del cielo, no dependen de datos natales): todos los suscriptores reciben el mismo payload.

Evento	Registro	Cuándo se dispara
retrograde-start	POST /v1/webhooks/retrograde-start	un planeta (de Mercurio a Plutón) se vuelve retrógrado
retrograde-end	POST /v1/webhooks/retrograde-end	un planeta sale de la retrogradación (se vuelve directo)
sign-ingress	POST /v1/webhooks/sign-ingress	un planeta (el Sol y de Mercurio a Plutón) entra en un nuevo signo
void-of-course-start	POST /v1/webhooks/void-of-course-start	empieza un periodo de Luna vacía de curso (VOC)
eclipse-alert	POST /v1/webhooks/eclipse-alert	7 días antes de un eclipse solar o lunar

Nota

Los eventos que dependen de la carta natal (transit-trigger, return-due, dasha-change, mahadasha-end) y el evento por ubicación planetary-hour-tick necesitan los datos natales o las coordenadas del suscriptor y se activarán en la siguiente fase.

Cómo suscribirse

Necesitas una clave API vinculada a tu cuenta.

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 }

Gestión de suscripciones: GET /v1/webhooks (lista), GET /v1/webhooks/{id}, DELETE /v1/webhooks/{id}, POST /v1/webhooks/{id}/test (entrega de prueba a tu URL).

Qué llega a tu URL

Un POST con las cabeceras X-AstroWay-Signature: sha256=<hmac>, X-AstroWay-Event, X-AstroWay-Delivery-Id y el cuerpo:

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

Verificación de la firma

La firma es HMAC-SHA256(signing_secret, raw_body) en hex. Compárala con la cabecera X-AstroWay-Signature (sin el prefijo 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 suscripción se desactiva automáticamente tras 5 entregas fallidas seguidas (no 2xx o timeout de 8 s). Vuelve a activarla desde GET /v1/webhooks → pausar/reanudar reinicia el contador.

Precio

El registro y la gestión de suscripciones cuestan Tier 1 (10 créditos) por llamada y se hacen pocas veces. La entrega del evento a tu URL no se factura: no tiene tarifa propia.