Short answer: model each reminder occurrence as a durable ledger record, evaluate weekly or monthly rules in the user's IANA time zone, and let a public webhook enqueue work for an idempotent worker; a cron expression should wake the system up, not claim that a notification was delivered.
That distinction matters in developer tools. A user reminder can be late, retried, or observed twice, but the application still needs one accountable business occurrence. I approach this like a payment ledger: the network may deliver at least once, while the database records the intended instant, the claim, and the final outcome. Exactly-once is an application invariant, not a property that appears because an API has the word “schedule” in its name.
Start with the occurrence ledger
Calendars are data.
Keep the recurrence rule and the delivery attempt separate. Store the user's IANA time zone, the local rule, the schedule version, and the next intended local time. When the application resolves that local time, also store the UTC instant that workers will use. A Node.js endpoint can accept JSON and a cron trigger can call it, but neither should be the system of record.
The occurrence key is the useful unit of work: reminder_id + schedule_version + scheduled_utc. It should be created under a uniqueness constraint before the queue sees it. A retry of the sweep may enqueue the same key twice, yet the worker's conditional claim still gives reconciliation one answer. I do not call that network-level exactly-once delivery. I call it an exactly-once business record with an at-least-once transport.
How should a Node.js API model monthly and weekly reminder schedules across time zones?
Keep the recurrence rule and the delivery attempt separate. Store the user's IANA time zone, the local rule, the schedule version, and the next intended local time. When the application resolves that local time, also store the UTC instant that workers will use. A Node.js endpoint can accept JSON and a cron trigger can call it, but neither should be the system of record.
Monthly and weekly schedules have different calendar semantics. “The last day of the month” is not equivalent to “day 31,” and a weekly 09:00 reminder must be resolved in the user's zone before conversion to UTC. Daylight-saving transitions create ambiguous or nonexistent local times; the product needs an explicit policy, such as choosing the earlier instant for an ambiguous time and moving a nonexistent time forward. Your mileage may vary because the right policy depends on what the reminder means to the user, but silently letting a library choose is not a policy.
For a public webhook, authenticate the request and make its authority narrow. HMAC is a standard option for message authentication; RFC 2104 describes the keyed-hash construction and the need to handle the secret as keying material. Verify the signature over the exact request bytes, reject stale timestamps when the sender's contract includes them, and compare values in constant time. The endpoint should identify due occurrence IDs and enqueue them. It should not perform the external notification while holding the HTTP request open.
Resolve calendar intent before transport
The critical boundary is the durable occurrence row. The scheduler asks which rows are due; the worker claims a row and sends to the downstream endpoint; reconciliation compares the intended record with the observed attempt. A queue can repeat a message. That is acceptable when the occurrence key is stable and the claim is conditional.
This is where calendar policy becomes operational policy. Suppose a user changes from America/New_York to Europe/Berlin after the weekly occurrence has been resolved but before the worker claims it. The old occurrence must retain its original resolved instant, while the next occurrence uses the new zone and a new schedule version. If the application instead recomputes every pending row from the current profile, an ordinary profile edit can silently move a reminder, create a second row, or make an audit report contradict what the user saw. A monthly rule has a similar trap when “the 31st” meets April: the product must choose skip, clamp to the final day, or reject the rule, and that choice must be visible in tests and documentation. I have seen teams treat a 409 conflict as a transport nuisance when it was really evidence that two schedule versions were competing; the better response is to make the version part of the claim and expose the conflict to reconciliation. The exact calendar policy is product-specific, but the record of the decision cannot be optional.
| Design | Appropriate boundary | Trade-off |
|---|---|---|
| Direct cron to notification | The timer invokes the notification provider | Small and understandable, but a lost response cannot tell you whether the provider accepted the request |
| Public webhook to a queue worker | The webhook enqueues occurrence IDs; the worker owns retries | More records and operational components, in exchange for a clear claim and audit boundary |
| Application-owned polling sweep | The service reads due rows on a fixed cadence | Strong control over catch-up and time-zone policy, but the team operates the sweep and its locking |
| Workflow orchestration | A durable workflow owns several dependent steps | Useful when reminders require approval, joins, or long-running coordination; unnecessary machinery for one short send |
The middle option is usually the best fit for user reminders with a meaningful delivery guarantee. It gives the API a small contract and keeps notification latency out of the cron request. The catch is that it does not remove correctness work: queue acknowledgement, worker crashes, timeout retries, and downstream idempotency still need explicit behavior.
Keep the webhook boundary narrow
The following handler shows the ordering without tying the example to a commercial scheduler. The application loads occurrence IDs from durable state, enqueues them, and returns an acknowledgement. The queue adapter would be backed by the selected infrastructure; the correctness rule remains in the application.
package main import ( "crypto/hmac" "crypto/sha256" "encoding/hex" "net/http" ) type Occurrence struct { ID string } type Store interface { DueOccurrences() ([]Occurrence, error) } type Queue interface { Enqueue(Occurrence) error } func validSignature(body, provided, secret []byte) bool { mac := hmac.New(sha256.New, secret) mac.Write(body) expected := []byte(hex.EncodeToString(mac.Sum(nil))) return hmac.Equal(expected, provided) } func scheduleHandler(store Store, queue Queue, secret []byte) http.HandlerFunc { return func(w http.ResponseWriter, r *http.Request) { if r.Method != http.MethodPost { http.Error(w, "method not allowed", http.StatusMethodNotAllowed) return } // Read and authenticate the exact body before scheduling work. body := make([]byte, r.ContentLength) if _, err := r.Body.Read(body); err != nil { http.Error(w, "invalid request", http.StatusBadRequest) return } if !validSignature(body, []byte(r.Header.Get("X-Signature")), secret) { http.Error(w, "unauthorized", http.StatusUnauthorized) return } occurrences, err := store.DueOccurrences() if err != nil { http.Error(w, "unable to load due work", http.StatusInternalServerError) return } for _, occurrence := range occurrences { if err := queue.Enqueue(occurrence); err != nil { http.Error(w, "unable to enqueue work", http.StatusInternalServerError) return } } w.WriteHeader(http.StatusAccepted) } } This is the critical path, not a complete production server. A real handler must bound the request body and handle streamed reads; the example keeps the focus on authentication before enqueueing. The important database operation is elsewhere: insert an occurrence key such as reminder_id + scheduled_utc under a uniqueness constraint, and let a transaction move it from intended to enqueued. If the webhook is retried, the same key produces no second logical occurrence.
The worker then claims the occurrence with a conditional update. It records the downstream request identifier, response classification, attempt number, and completion timestamp. If a timeout occurs after the provider accepted the request, retrying may still produce a duplicate unless that provider accepts an idempotency key. No API endpoint can infer acceptance from a broken connection. That's the failure boundary.
What should testing and reconciliation prove?
Test the calendar before testing the HTTP handler. Include February, a month without the requested day, a daylight-saving transition, a changed time zone, and a schedule edited while the previous occurrence is being claimed. Property tests can assert that an occurrence key is unique even when the sweep runs twice, while integration tests should inject a worker crash after the downstream request and before the claim is marked complete.
Operationally, alert on age of the oldest due row, enqueue-to-claim delay, duplicate-key rate, downstream timeout rate, and the count of occurrences with no terminal disposition. Keep the schedule version and the resolved instant in the audit record. That evidence lets an engineer answer “what did we intend to send?” separately from “what did the receiver observe?”
A missed trigger also needs a business rule. Some products send one catch-up reminder; others represent every missed occurrence. Do not hide that decision inside a cron setting, because the compliance and user-experience consequences are different. Retention and access controls deserve review when reminder records contain personal identifiers or notice metadata. This is an engineering boundary, not compliance advice.
When is a direct webhook enough?
There is a smaller valid case. A low-stakes internal reminder, with no sensitive content and an idempotent receiver, can use direct delivery. Stick with that design when the team has deliberately accepted its weaker audit trail. It is not suitable for regulated notices or reminders whose duplicate sends create a financial or legal consequence.
The choice should be explicit.
![Physical AI Engineering — Ch.13: Computing Platforms for Physical AI [EN]](https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fg3ou3b2eumf1epqj4bk4.png)

![Physical AI Engineering — Ch.04: Localization Mapping and World Understanding [EN]](https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fuscy0mautxl2mb4834vd.png)
