Notificações Cósmicas - Webhooks para Eventos Astronômicos

Transforma a AstroWay API de request-response para stream de eventos. Em vez de sondar o céu em ciclo, tu subscreves um URL a um tipo de evento - e a AstroWay envia o webhook no momento em que ocorre (assinado HMAC‑SHA256, com reintentos automáticos e desativação automática de subscrições “mortas”).

Quais eventos (live)

Todas estas eventos são globais (estado do céu, não depende de dados natais) - os subscritores recebem o mesmo payload.

Evento	Registo	Quando dispara
retrograde-start	POST /v1/webhooks/retrograde-start	planeta (Mercúrio–Plutão) torna‑se retrógrado
retrograde-end	POST /v1/webhooks/retrograde-end	planeta sai da retrograda (torna‑se direta)
sign-ingress	POST /v1/webhooks/sign-ingress	planeta (Sol + Mercúrio–Plutão) entra num novo signo
void-of-course-start	POST /v1/webhooks/void-of-course-start	começa o período da Lua «sem curso» (VOC)
eclipse-alert	POST /v1/webhooks/eclipse-alert	7 dias antes de um eclipse solar ou lunar

Nota

Eventos dependentes de nascimento - transit-trigger, return-due, dasha-change, mahadasha-end - e o evento por localização planetary-hour-tick requerem dados de nascimento / coordenadas do subscritor e serão ativados na próxima fase.

Como subscrever

É necessário uma chave API associada à tua conta.

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 }

Gerir subscrições: GET /v1/webhooks (lista), GET /v1/webhooks/{id}, DELETE /v1/webhooks/{id}, POST /v1/webhooks/{id}/test (entrega de teste para o teu URL).

O que chega ao teu URL

POST com os cabeçalhos X-AstroWay-Signature: sha256=<hmac>, X-AstroWay-Event, X-AstroWay-Delivery-Id e o 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ção da assinatura

A assinatura é HMAC-SHA256(signing_secret, raw_body) em hex. Compara com o cabeçalho X-AstroWay-Signature (sem o prefixo 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));
}

A subscrição desativa‑se automaticamente após 5 entregas consecutivas falhadas (não‑2xx ou timeout de 8 s) - reativa‑a novamente via GET /v1/webhooks → pausa/retoma reinicia o contador.

Preço

Registo e gestão de subscrições - Tier 1 (10 créditos) por chamada, são raras. A entrega do evento ao teu URL não tem tarifação - não há tarifa separada.