Cosmic Notifications - webhook untuk peristiwa astrologi

Ubah AstroWay API dari request-response menjadi aliran peristiwa. Alih-alih memeriksa langit berulang-ulang dalam loop, Anda melanggankan sebuah URL ke satu jenis peristiwa, dan AstroWay sendiri yang mengirim webhook saat peristiwa itu terjadi (ditandatangani HMAC-SHA256, dengan percobaan ulang otomatis dan penonaktifan otomatis langganan yang “mati”).

Peristiwa yang tersedia (live)

Semua peristiwa ini bersifat global (keadaan langit, tidak bergantung pada data kelahiran): semua pelanggan menerima payload yang sama.

Peristiwa	Pendaftaran	Kapan dipicu
retrograde-start	POST /v1/webhooks/retrograde-start	planet (Merkurius–Pluto) mulai retrograde
retrograde-end	POST /v1/webhooks/retrograde-end	planet keluar dari retrograde (menjadi direct)
sign-ingress	POST /v1/webhooks/sign-ingress	planet (Matahari + Merkurius–Pluto) memasuki rasi baru
void-of-course-start	POST /v1/webhooks/void-of-course-start	dimulainya periode Bulan “void of course” (VOC)
eclipse-alert	POST /v1/webhooks/eclipse-alert	7 hari sebelum gerhana matahari atau gerhana bulan

Catatan

Peristiwa yang bergantung pada data kelahiran (transit-trigger, return-due, dasha-change, mahadasha-end) dan peristiwa berbasis lokasi planetary-hour-tick memerlukan data kelahiran / koordinat pelanggan dan akan diaktifkan pada fase berikutnya.

Cara berlangganan

Anda memerlukan API key yang terikat ke akun Anda.

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 }

Mengelola langganan: GET /v1/webhooks (daftar), GET /v1/webhooks/{id}, DELETE /v1/webhooks/{id}, POST /v1/webhooks/{id}/test (pengiriman uji ke URL Anda).

Apa yang tiba di URL Anda

Sebuah POST dengan header X-AstroWay-Signature: sha256=<hmac>, X-AstroWay-Event, X-AstroWay-Delivery-Id dan 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
  }
}

Verifikasi tanda tangan

Tanda tangannya adalah HMAC-SHA256(signing_secret, raw_body) dalam hex. Cocokkan dengan header X-AstroWay-Signature (tanpa prefiks 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));
}

Langganan dinonaktifkan otomatis setelah 5 pengiriman gagal berturut-turut (bukan 2xx atau timeout 8 detik). Aktifkan kembali melalui GET /v1/webhooks → jeda/lanjutkan akan mereset penghitungnya.

Harga

Pendaftaran dan pengelolaan langganan dikenai Tier 1 (10 kredit) per panggilan, dan jarang dilakukan. Pengiriman peristiwa ke URL Anda tidak ditagih: tidak ada tarif terpisah.