Documentation
Observance reminders
Get a signed webhook before Ekadashi, Purnima, Amavasya, Pradosh, Sankashti, a festival, a Sankranti, an eclipse or each day's Rahu Kaal, at your place and lead time.
An observance subscription asks the API to remind you of one kind of observance at one place. The API works out when each one falls, and sends an observance.upcoming webhook to the endpoint you choose, the lead time you ask for before it. You do not poll and you do not keep a calendar: you receive an event when a reminder is due.
Subscriptions need a secret key. Creating, changing and deleting them costs no credits, and each event delivered is free too (see Cost and limits). You can also manage them in the dashboard under Webhooks, Observance reminders.
Before you start
- Create a webhook endpoint in the dashboard (or
POSTit to the portal) and tick the Observance reminder event,observance.upcoming. A subscription names one endpoint, and the endpoint must be in the same environment as your key: a test key uses sandbox endpoints, a live key uses live ones. - Know the place: latitude, longitude and an IANA time zone (or a fixed
utc_offset). Latitude must be within 66° of the equator, because observances are judged from sunrise.
Subscribe
POST /v1/subscriptions/observances
Authorization: Bearer sk_live_...
{
"kind": "ekadashi",
"endpoint_id": "6d4a1f9e-3b0c-4c8e-9d55-2f6a8b7e1c40",
"lead_minutes": 1440,
"latitude": 28.6139,
"longitude": 77.209,
"timezone": "Asia/Kolkata",
"label": "Delhi temple"
}| Field | Meaning |
|---|---|
kind | What to be reminded of. See the table below. |
endpoint_id | One of your webhook endpoints, in the key's environment, subscribed to observance.upcoming. |
latitude, longitude | The place, within 66° of the equator. |
timezone or utc_offset | Send exactly one. Times in the event are in this zone. |
lead_minutes | Send the event this many minutes before the observance: 0 to 43,200 (30 days). One hour is 60, one day 1,440. Default 0. |
festivals | For kind: "festival" only: keep festivals whose name contains one of these words (case-insensitive, up to 20). Empty means every festival. |
label | Your own note, up to 120 characters. |
kind | When it falls (occurs_at) | Calculated with |
|---|---|---|
ekadashi | The start of the Smarta observance day (local midnight). The event names it (Utpanna Ekadashi...) and carries the tithi start and end and the parana window. | ekadashi-calendar |
purnima, amavasya, pradosh, sankashti | The moment the day is judged: sunrise, or the evening window for Pradosh. | vrat-calendar |
festival | Sunrise of the festival's day, or local midnight when the day has no sunrise value. One event per festival, so a day with two festivals sends two. | festival-calendar |
sankranti | The exact moment the Sun enters a sign, with the Punya Kaal and the Maha Punya Kaal. | sankranti-detail |
eclipse | The moment of greatest eclipse. The event says whether it is visible at your place. | eclipses |
rahu_kaal_daily | The start of each day's Rahu Kaal. Lead time up to 720 minutes. | daily-panchang |
The reminders agree with what those capabilities return for the same place, because they are calculated with them.
The response is the subscription with its id and its next occurrences. GET /v1/subscriptions/observances lists your subscriptions (kind filters, limit up to 200), GET /v1/subscriptions/observances/{id} shows one with its next ten, and DELETE /v1/subscriptions/observances/{id} removes it with the occurrences not yet sent.
PATCH /v1/subscriptions/observances/{id}
{ "lead_minutes": 60, "active": true }PATCH changes label, lead_minutes, endpoint_id, festivals and active (false pauses it). The kind and the place cannot change: create a new subscription instead. When you change the lead time, occurrences not yet sent move with it, and one whose new send time has already passed is skipped rather than sent late.
The event
The endpoint receives the same signed envelope as every webhook (Astro-Signature, retries, the delivery log: see jobs and webhooks), with type set to observance.upcoming:
{
"id": "evt_5e1c0d...",
"type": "observance.upcoming",
"created": 1796000000,
"environment": "live",
"project_id": null,
"data": {
"subscription_id": "0a8b2c6e-...",
"label": "Delhi temple",
"kind": "ekadashi",
"title": "Utpanna Ekadashi",
"occurs_at": "2026-12-04T00:00:00+05:30",
"lead_minutes": 1440,
"place": { "latitude": 28.6139, "longitude": 77.209, "timezone": "Asia/Kolkata" },
"observance": {
"date": "2026-12-04",
"paksha": "Krishna",
"lunar_month": "Margashirsha",
"tithi_start": "2026-12-03T10:00:00+05:30",
"tithi_end": "2026-12-04T09:00:00+05:30",
"parana": { "date": "2026-12-05", "start": "2026-12-05T07:00:00+05:30", "end": "2026-12-05T09:00:00+05:30" },
"at_means": "start of the observance day (local midnight)"
}
}
}data.observance holds the details of that kind (a Sankranti has the sign and the Punya Kaal, an eclipse its type and visibility, Rahu Kaal its start and end). at_means says what occurs_at stands for. Use the event id (the Astro-Webhook-Id header) to ignore a repeat: a delivery that your server answered late may arrive twice.
When events are sent
The worker sends each occurrence once, at its occurs_at minus lead_minutes, to within about a minute. It keeps about 13 months of occurrences ahead (3 days for rahu_kaal_daily) and tops the list up, so a subscription keeps working without any action. Each occurrence is sent at most once even if two workers run at the same moment.
Some occurrences are never sent, and GET /v1/subscriptions/observances/{id} counts them as skipped:
- An occurrence whose send time had already passed when it was found, for example when you subscribe a day before an Ekadashi with a two-day lead. A reminder is not sent late for something already close.
- An occurrence the worker could not reach for more than 30 minutes after it happened (for example during an outage).
- An occurrence whose endpoint was deleted, disabled or no longer subscribed to
observance.upcoming, or whose live endpoint's plan no longer includes live webhooks.
Pausing a subscription (active: false) sends nothing until you resume it.
Cost and limits
Delivered events are free. Like the astrology events of a saved chart, a reminder costs no credits: the calculation behind it is bounded instead by these limits, per organization and environment:
- up to 50 subscriptions;
- up to 3
rahu_kaal_dailysubscriptions, because each one asks the engine every day; lead_minutesup to 30 days (12 hours forrahu_kaal_daily).
Live subscriptions need a plan that includes live webhooks (sandbox works on every plan). Delivery follows the webhook endpoint's rules: a live endpoint that fails for three days is disabled, and its pending deliveries close. If you need the same data on demand instead, the today-feed capability (POST /v1/panchang/today-feed) returns a day's panchang, festivals, events and the next observances in one call for 5 credits.
Errors
| Status | Code | When |
|---|---|---|
404 | not_found | The endpoint_id is not an endpoint of this environment, or the subscription does not exist. |
422 | invalid_request | An unknown kind, a place outside 66°, both or neither of timezone and utc_offset, a lead_minutes out of range, or an endpoint that is not subscribed to observance.upcoming. The error names the field. |
403 | plan_required | A live subscription on a plan without live webhooks. |
403 | publishable_key_not_allowed | A publishable key. Use a secret key from your server. |
409 | limit_reached | You are at a limit above. |
Was this page helpful?
Saved charts and astrology events
Store a birth once, call any capability with its chart_id, and get webhooks when a dasha begins, Sade Sati turns or an eclipse hits the chart.
Audio reports
Turn any report into a spoken MP3 in 31 languages including Hinglish, with 18 voices, 12 styles, a two-voice podcast format and an optional music bed.


