Cosmic Notifications - webhook cho các sự kiện chiêm tinh

Biến AstroWay API từ mô hình request-response thành luồng sự kiện. Thay vì liên tục thăm dò bầu trời trong một vòng lặp, bạn đăng ký một URL cho một loại sự kiện, và AstroWay sẽ tự gửi webhook ngay khi sự kiện xảy ra (ký bằng HMAC-SHA256, có tự động gửi lại và tự động vô hiệu hóa các subscription “chết”).

Các sự kiện (live)

Tất cả các sự kiện này đều mang tính toàn cục (trạng thái bầu trời, không phụ thuộc dữ liệu bản đồ sao cá nhân): mọi subscriber nhận cùng một payload.

Sự kiện	Đăng ký	Khi nào kích hoạt
retrograde-start	POST /v1/webhooks/retrograde-start	một hành tinh (Sao Thủy đến Sao Diêm Vương) bắt đầu nghịch hành
retrograde-end	POST /v1/webhooks/retrograde-end	một hành tinh kết thúc nghịch hành (trở lại thuận hành)
sign-ingress	POST /v1/webhooks/sign-ingress	một hành tinh (Mặt Trời và Sao Thủy đến Sao Diêm Vương) đi vào cung mới
void-of-course-start	POST /v1/webhooks/void-of-course-start	bắt đầu giai đoạn Trăng vô định (VOC)
eclipse-alert	POST /v1/webhooks/eclipse-alert	7 ngày trước nhật thực hoặc nguyệt thực

Ghi chú

Các sự kiện phụ thuộc bản đồ sao cá nhân (transit-trigger, return-due, dasha-change, mahadasha-end) và sự kiện theo vị trí planetary-hour-tick cần dữ liệu bản đồ sao hoặc tọa độ của subscriber, và sẽ được bật trong giai đoạn tiếp theo.

Cách đăng ký

Bạn cần một API key gắn với tài khoản của mình.

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 }

Quản lý subscription: GET /v1/webhooks (danh sách), GET /v1/webhooks/{id}, DELETE /v1/webhooks/{id}, POST /v1/webhooks/{id}/test (gửi thử tới URL của bạn).

Dữ liệu gửi tới URL của bạn

Một POST với các header X-AstroWay-Signature: sha256=<hmac>, X-AstroWay-Event, X-AstroWay-Delivery-Id và body:

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

Xác minh chữ ký

Chữ ký là HMAC-SHA256(signing_secret, raw_body) ở dạng hex. So sánh với header X-AstroWay-Signature (bỏ tiền tố 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));
}

Subscription sẽ tự động bị vô hiệu hóa sau 5 lần gửi thất bại liên tiếp (không phải 2xx hoặc timeout 8 giây). Bạn có thể bật lại qua GET /v1/webhooks → tạm dừng rồi tiếp tục sẽ đặt lại bộ đếm.

Giá

Đăng ký và quản lý subscription có giá Tier 1 (10 credit) mỗi lần gọi, và thường hiếm khi thực hiện. Việc gửi sự kiện tới URL của bạn không bị tính phí: không có biểu giá riêng.