# 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](https://96astroapi.com/docs/jobs-and-webhooks.md) 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](#cost-and-limits)). You can also manage them in the dashboard under **Webhooks, Observance reminders**.

## Before you start

1. Create a webhook endpoint in the dashboard (or `POST` it 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.
2. 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

```http
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.

```http
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](https://96astroapi.com/docs/jobs-and-webhooks.md)), with `type` set to `observance.upcoming`:

```json
{
  "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](https://96astroapi.com/docs/saved-charts.md), 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_daily` subscriptions, because each one asks the engine every day;
- `lead_minutes` up to 30 days (12 hours for `rahu_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. |
