Cosmic Notifications : webhooks sur les événements astrologiques

Fais passer AstroWay API du modèle requête-réponse à un flux d’événements. Au lieu d’interroger le ciel en boucle, tu abonnes une URL à un type d’événement, et AstroWay envoie lui-même un webhook au moment où il se produit (signé en HMAC-SHA256, avec nouvelles tentatives automatiques et désactivation automatique des abonnements “morts”).

Quels événements (live)

Tous ces événements sont globaux (état du ciel, indépendant des données natales) : tous les abonnés reçoivent le même payload.

Événement	Enregistrement	Quand il se déclenche
retrograde-start	POST /v1/webhooks/retrograde-start	une planète (de Mercure à Pluton) devient rétrograde
retrograde-end	POST /v1/webhooks/retrograde-end	une planète sort de la rétrogradation (redevient directe)
sign-ingress	POST /v1/webhooks/sign-ingress	une planète (le Soleil + de Mercure à Pluton) entre dans un nouveau signe
void-of-course-start	POST /v1/webhooks/void-of-course-start	début d’une période de Lune “hors cours” (VOC)
eclipse-alert	POST /v1/webhooks/eclipse-alert	7 jours avant une éclipse solaire ou lunaire

Note

Les événements dépendant du thème natal (transit-trigger, return-due, dasha-change, mahadasha-end) et l’événement lié à la localisation planetary-hour-tick nécessitent les données natales ou les coordonnées de l’abonné et seront activés dans la phase suivante.

Comment s’abonner

Il faut une clé API liée à ton compte.

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 }

Gérer les abonnements : GET /v1/webhooks (liste), GET /v1/webhooks/{id}, DELETE /v1/webhooks/{id}, POST /v1/webhooks/{id}/test (livraison de test vers ton URL).

Ce qui arrive sur ton URL

Un POST avec les en-têtes X-AstroWay-Signature: sha256=<hmac>, X-AstroWay-Event, X-AstroWay-Delivery-Id et le corps :

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

Vérification de la signature

La signature est HMAC-SHA256(signing_secret, raw_body) en hex. Compare-la à l’en-tête X-AstroWay-Signature (sans le préfixe 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 abonnement est désactivé automatiquement après 5 livraisons échouées d’affilée (réponse non-2xx ou timeout de 8 s) ; réactive-le via GET /v1/webhooks → une mise en pause suivie d’une reprise remet le compteur à zéro.

Prix

L’enregistrement et la gestion des abonnements coûtent Tier 1 (10 crédits) par appel, et ces appels sont rares. La livraison d’un événement vers ton URL n’est pas facturée : il n’y a pas de tarif séparé.