Cosmic Notifications - thông báo vũ trụ

Chuyển đổi AstroWay API từ request-response thành streaming. Thay vì hỏi bầu trời trong vòng lặp, bạn đăng ký URL theo kiểu sự kiện - và AstroWay sẽ gửi webhook vào thời điểm đó (chứng nhận HMAC-SHA256, với tự động lặp lại và tự động tắt “morts” đăng ký).

Các sự kiện (live)

Tất cả các sự kiện này là toàn cầu (tình trạng bầu trời, không phụ thuộc vào dữ liệu cá nhân) - người đăng ký sẽ nhận payload giống nhau.

Sự kiện	Đăng ký	Khi xảy ra
`retrograde-start`	`POST /v1/webhooks/retrograde-start`	oplanet (Merkury–Pluto) trở thành retrograde
`retrograde-end`	`POST /v1/webhooks/retrograde-end`	oplanet thoát khỏi retro (trở thành trực tiếp)
`sign-ingress`	`POST /v1/webhooks/sign-ingress`	oplanet (Sun + Merkury–Pluto) vào dấu hiệu mới
`void-of-course-start`	`POST /v1/webhooks/void-of-course-start`	Bắt đầu giai đoạn Mặt Trăng “bỏ cuộc” (VOC)
`eclipse-alert`	`POST /v1/webhooks/eclipse-alert`	Trong 7 ngày trước khi xảy ra nhật thực hoặc nguyệt thực

Tạo đăng ký

Cần có API-key, liên kết với tài khoản của bạn.

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 }

Quản lý đăng ký: GET /v1/webhooks (danh sách), GET /v1/webhooks/{id}, DELETE /v1/webhooks/{id}, POST /v1/webhooks/{id}/test (dữ liệu thử nghiệm đến URL của bạn).

Điều gì đến với URL của bạn

POST với tiêu đề X-AstroWay-Signature: sha256=<hmac>, X-AstroWay-Event, X-AstroWay-Delivery-Id và nội dung:

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

Kiểm tra chữ ký

Chữ ký là HMAC-SHA256(signing_secret, raw_body) trong hex. Kiểm tra với tiêu đề 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));
}

Đăng ký tự động tắt sau 5 lần giao tiếp liên tiếp không thành công (không-2xx hoặc thời gian chờ 8 s) - hãy bật lại qua GET /v1/webhooks → tạm dừng/đóng lại sẽ bỏ qua số lần giao tiếp.

Giá

Đăng ký và quản lý đăng ký - Tier 1 (10 credits) cho mỗi lần gọi, được thực hiện ít. Giao tiếp sự kiện đến URL của bạn không tính phí - không có phí riêng biệt.

Hữu ích chứ?

Запропонувати правку

Cập nhật lần cuối: 10 thg 9, 2026