# Cosmic Notifications — вебхуки на астрособытія

Перетворіть AstroWay API з request-response на **подієвий стрім**. Замість того щоб опитувати небо в циклі, ви підписуєте URL на тип події — і AstroWay сам надсилає вебхук у момент її настання (підписаний HMAC-SHA256, з авто-повторами та авто-відключенням «мертвих» підписок).

## Які події (live)

Усі ці події **глобальні** (стан неба, не залежить від натальних даних) — підписники отримують однаковий payload.

| Подія | Реєстрація | Коли спрацьовує |
|---|---|---|
| `retrograde-start` | `POST /v1/webhooks/retrograde-start` | планета (Меркурій–Плутон) стає ретроградною |
| `retrograde-end` | `POST /v1/webhooks/retrograde-end` | планета виходить із ретро (стає директною) |
| `sign-ingress` | `POST /v1/webhooks/sign-ingress` | планета (Сонце + Меркурій–Плутон) входить у новий знак |
| `void-of-course-start` | `POST /v1/webhooks/void-of-course-start` | починається період Місяця «без курсу» (VOC) |
| `eclipse-alert` | `POST /v1/webhooks/eclipse-alert` | за 7 днів до сонячного або місячного затемнення |

<Aside type="note">
Натально-залежні події — `transit-trigger`, `return-due`, `dasha-change`, `mahadasha-end` — та подія за локацією `planetary-hour-tick` потребують натальних даних / координат підписника й увімкнуться у наступній фазі.
</Aside>

## Як підписатися

Потрібен API-ключ, прив'язаний до вашого акаунта.

```bash
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 }
```

Керувати підписками: `GET /v1/webhooks` (список), `GET /v1/webhooks/{id}`, `DELETE /v1/webhooks/{id}`, `POST /v1/webhooks/{id}/test` (тестова доставка на ваш URL).

## Що приходить на ваш URL

`POST` із заголовками `X-AstroWay-Signature: sha256=<hmac>`, `X-AstroWay-Event`, `X-AstroWay-Delivery-Id` і тілом:

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

## Перевірка підпису

Підпис — це `HMAC-SHA256(signing_secret, raw_body)` у hex. Звіряйте з заголовком `X-AstroWay-Signature` (без префікса `sha256=`):

```js

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));
}
```

Підписка авто-відключається після **5 поспіль невдалих доставок** (не-2xx або таймаут 8 с) — увімкніть її знову через `GET /v1/webhooks` → пауза/відновлення скидає лічильник.

## Ціна

Реєстрація та керування підписками — **Tier 1 (10 кредитів)** за виклик, виконуються рідко. **Доставка події на ваш URL не тарифікується** — окремого тарифу немає.