Cosmic Notifications - アストロイベント用のWebフック

AstroWay API を request-response から イベントストリーム に変換しよう。空をループでポーリングする代わりに、URL をイベントタイプにサブスクライブすれば、AstroWay がその瞬間に webhook を自動送信してくれる（HMAC-SHA256 で署名、再送自動、そして「死んだ」サブスクリプションの自動解除付き）。

どのイベント (ライブ)

すべてのイベントは グローバル（空の状態で、出生データに依存しない）で、購読者は同じ 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日前

どうやってサブスクライブするか

アカウントに紐付いた API キーが必要だ。

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 とボディが含まれる:

{
  "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= を除く）と比較しよう:

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

サブスクリプションは 5 回連続で配信失敗（2xx 以外または 8 秒タイムアウト）すると自動で解除される。GET /v1/webhooks で再度有効化でき、ポーズ/再開でカウンタがリセットされる。

料金

サブスクリプションの登録と管理は Tier 1（10 クレジット） の呼び出しごとに課金され、頻繁には行われない。あなたの URL へのイベント配信は課金対象外 で、別途料金は発生しない。

参考になりましたか？