A nightly payment reconciliation can wait a few hours; a user reminder tied to a local calendar cannot drift into the wrong day. Short answer: use an API that stores the user's timezone and recurrence rule, emits a unique occurrence ID to a public webhook endpoint, and lets the receiver retry safely; keep the nightly reconciliation as the cheaper batch job that decides which reminder schedules should exist.
That split is the whole decision. Cron is an execution mechanism, not a complete model for “the last day of every month at 9:00 AM in this subscriber's timezone.” The scheduler owns calendar math. The media SaaS owns payment state, message eligibility, and delivery history. Don't make one process pretend to own all three.
For a one-person product, this matters more than a long feature matrix. Every hour spent debugging calendar edge cases is an hour not spent shipping the next weekly release. Outsource the undifferentiated timer machinery, but keep the small amount of business logic that protects revenue in code you control.
How should a public webhook API schedule recurring user reminders across timezones?
Start by separating the rule from its next execution. A weekly rule can be described as a weekday, local clock time, and IANA timezone identifier. A monthly rule also needs an explicit policy for dates that don't occur in every month. “Day 31” might mean skip that month or use its final calendar day. Either behavior can be valid. An API that leaves the choice implicit isn't suitable for billing-adjacent reminders because two developers can read the same schedule differently. The stored record should include a stable schedule ID, a timezone, a recurrence rule, the next calculated occurrence, and a policy version. The webhook event should include a separate occurrence ID. That distinction is easy to miss: the schedule identifies the continuing intent, while the occurrence identifies one attemptable piece of work. If an acknowledgment is lost and the same event arrives again, the receiver can recognize it without suppressing next week's reminder.
For the media example, the nightly reconciliation reads the payment provider's settled view and the local subscription ledger. It doesn't send messages. It creates, updates, or cancels reminder intent for accounts that need action, then the scheduling layer invokes the endpoint at the user's local time. This lets reconciliation run in a low-cost batch window while reminder delivery keeps the tighter latency target that users actually notice.
Keep the calendar decision visible in data. A compact record could look like this:
type ReminderSchedule = {
scheduleId: string;
accountId: string;
cadence:
| { kind: "weekly"; weekday: 1 | 2 | 3 | 4 | 5 | 6 | 7 }
| { kind: "monthly"; day: number; missingDay: "skip" | "last-day" };
localTime: `${number}:${number}`;
timezone: string;
policyVersion: 1;
status: "active" | "paused";
};
const renewalReminder: ReminderSchedule = {
scheduleId: "rem_media_1042",
accountId: "acct_1042",
cadence: { kind: "monthly", day: 31, missingDay: "last-day" },
localTime: "09:00",
timezone: "America/New_York",
policyVersion: 1,
status: "active",
};
Those example values are decisions, not universal defaults. Your mileage may vary. The important part is that the choices are stored rather than buried inside a five-field cron expression.
Build the smallest receiver that can be retried
The public endpoint has a narrow job: authenticate the bytes it received, validate the event shape, claim the occurrence once, and enqueue business work. It should return quickly. The actual email or push notification belongs behind that boundary, so a slow downstream channel doesn't turn into repeated webhook attempts.
Use a keyed message authentication code over the raw request body. RFC 2104 defines HMAC as a mechanism for message authentication using cryptographic hash functions and a shared secret. The exact header name and payload envelope are part of your own webhook contract. Document them, rotate the secret deliberately, and compare signatures without an early-exit string comparison.
This TypeScript sketch shows the application boundary. claimOccurrence must be an atomic insert backed by a unique constraint on occurrenceId; enqueueReminder can target whatever queue the application already operates. The code returns 401 for a bad signature and accepts a duplicate with 202, because the duplicate is already accounted for and retrying it adds no value.
import { createHmac, timingSafeEqual } from "node:crypto";
import { createServer } from "node:http";
type ReminderEvent = {
occurrenceId: string;
scheduleId: string;
accountId: string;
scheduledFor: string;
};
declare function claimOccurrence(occurrenceId: string): Promise<boolean>;
declare function enqueueReminder(event: ReminderEvent): Promise<void>;
const secret = process.env.REMINDER_WEBHOOK_SECRET;
if (!secret) throw new Error("REMINDER_WEBHOOK_SECRET is required");
function validSignature(body: Buffer, suppliedHex: string): boolean {
const expected = createHmac("sha256", secret).update(body).digest();
const supplied = Buffer.from(suppliedHex, "hex");
return supplied.length === expected.length && timingSafeEqual(supplied, expected);
}
const server = createServer(async (request, response) => {
if (request.method !== "POST" || request.url !== "/webhooks/reminders") {
response.writeHead(404).end();
return;
}
const chunks: Buffer[] = [];
for await (const chunk of request) chunks.push(Buffer.from(chunk));
const body = Buffer.concat(chunks);
const signature = String(request.headers["x-reminder-signature"] ?? "");
if (!validSignature(body, signature)) {
response.writeHead(401).end();
return;
}
const event = JSON.parse(body.toString("utf8")) as ReminderEvent;
const claimed = await claimOccurrence(event.occurrenceId);
if (claimed) await enqueueReminder(event);
response.writeHead(202).end();
});
server.listen(3000);
That's enough for the delivery edge.
The queue handoff matters because it separates acceptance latency from processing latency. A messaging system such as the model described in the Google Cloud Pub/Sub overview decouples services that produce events from services that process them. The article's design doesn't require that product; the architectural property is the useful part. A database-backed queue can be a better fit at small volume when adding another operated system would cost more founder time than it saves.
Test the receiver with the same raw bytes used to calculate the signature. Then exercise duplicate occurrence IDs, a changed payload with an old signature, a paused schedule, and a monthly rule crossing a short month. Test a timezone offset change too. A passing “every 24 hours” test does not prove that a local 9:00 AM rule remains at 9:00 AM.
How should latency and cost choose between batch and event paths?
The cost mistake is buying low latency for work that has no low-latency requirement. Nightly payment reconciliation is a batch: read a bounded set, compare states, record decisions, and checkpoint progress. User-facing reminder invocation is different. It needs enough timing precision to preserve the promised local window, but it still shouldn't repeat payment-provider reads for every subscriber occurrence.
| Work | Useful latency target | Cost posture | Failure boundary |
|---|---|---|---|
| Payment reconciliation | Complete within the nightly window | Batch reads and bounded concurrency | Resume from a durable checkpoint |
| Schedule maintenance | After reconciliation decisions | Write only changed reminder intent | Upsert by stable schedule ID |
| Webhook acceptance | Short request path | Authenticate, claim, and enqueue | Retry by occurrence ID |
| Message processing | Channel-dependent | Scale consumers independently | Record outcome against the occurrence |
This is also where “best API” becomes a local answer. Choose against behavior you can test: timezone identifiers rather than fixed offsets, explicit weekly and monthly rules, a documented missing-day policy, signed webhook delivery, unique event identifiers, retry semantics, and a way to pause or update a schedule without creating two active copies. Public endpoint support alone is too thin a criterion.
I'm not sure what reminder latency your publication's audience will tolerate; analytics and support data should settle that. A five-minute window and a one-hour window lead to different execution costs. They do not change the data model. Write the service-level objective down, observe scheduled time versus accepted time, and avoid paying for precision nobody can perceive.
One hard limit remains: a managed scheduling API is not suitable when reminders require sub-second coordination with an in-process transaction. Keep that work inside the transactional system or its outbox. At the other extreme, stick with a simple self-hosted cron process when every reminder shares one timezone, monthly calendar policy is irrelevant, volume is modest, and operating that process is already routine. Externalizing it would add a webhook and secret lifecycle without removing meaningful work.
What I would change when the reminder volume grows
At higher volume, partition the occurrence ledger, put reconciliation checkpoints in durable storage, and apply backpressure before the delivery channel. Preserve the same schedule and occurrence identifiers. Scale should change the plumbing, not the meaning of a reminder.
I would also retain policy versions with generated occurrences long enough to answer one operational question: “Why was this reminder due then?” A timezone update, cadence edit, or missing-day policy change can otherwise make yesterday's correct decision look inexplicable. This is audit data, not a second scheduler.
Don't optimize this path first. Ship weekly. Instrument accepted delay, duplicate rate, queue age, and end-to-end delivery outcome; change the design after one of those signals shows a real constraint. For a solo SaaS, revenue per engineering hour is the useful lens — a theoretically elegant scheduler that consumes the feature calendar is still an expensive scheduler.
Top comments (0)