Cosmic Notifications: ज्योतिषीय घटनाओं के लिए वेबहुक

Last updated 29 सित॰ 2026 Markdown के रूप में देखें एजेंट सेटअप

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 दिन पहले

सब्सक्राइब कैसे करें

आपके खाते से जुड़ी 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…",   ← store it; it verifies the signature
#   "active": true }

सब्सक्रिप्शन प्रबंधन: GET /v1/webhooks (सूची), GET /v1/webhooks/{id}, DELETE /v1/webhooks/{id}, POST /v1/webhooks/{id}/test (आपके URL पर टेस्ट डिलीवरी)।

आपके URL पर क्या आता है

हेडर X-AstroWay-Signature: sha256=<hmac>, X-AstroWay-Event, X-AstroWay-Delivery-Id और इस body के साथ एक POST:

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

हस्ताक्षर की जाँच

हस्ताक्षर hex में HMAC-SHA256(signing_secret, raw_body) है। इसे 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 असफल डिलीवरी (non-2xx या 8 सेकंड का टाइमआउट) के बाद सब्सक्रिप्शन अपने आप निष्क्रिय हो जाता है। इसे GET /v1/webhooks के ज़रिए फिर से चालू करें → पॉज़/रिज़्यूम काउंटर को रीसेट कर देता है।

कीमत

सब्सक्रिप्शन का रजिस्ट्रेशन और प्रबंधन Tier 1 (10 क्रेडिट) प्रति कॉल है, ये कभी-कभार ही होते हैं। आपके URL पर इवेंट की डिलीवरी का शुल्क नहीं लगता: इसका कोई अलग टैरिफ़ नहीं है।