Countdown Timer API vs building it yourself

Version one is easy

It really is. A table, an index, and a worker. If your deadlines are internal, low volume, and nobody sees a countdown, you may never need more than this — and adopting a service for it would be overkill.

// Version one. Ships in an afternoon and is genuinely fine.
CREATE TABLE deadlines (
  id          uuid PRIMARY KEY,
  record_id   uuid NOT NULL,
  expires_at  timestamptz NOT NULL,
  fired_at    timestamptz
);

-- Plus a worker that polls it.
SELECT id, record_id FROM deadlines
WHERE expires_at <= NOW() AND fired_at IS NULL
LIMIT 100;

This works until it does not, and the ways it stops working arrive in a predictable order.

Versions two through four are the actual work

-- Version two, after the first production incident:
-- two workers processed the same rows.
SELECT id, record_id FROM deadlines
WHERE expires_at <= NOW() AND fired_at IS NULL
ORDER BY expires_at
LIMIT 100
FOR UPDATE SKIP LOCKED;   -- now correct under concurrency

-- Version three, after a downstream outage lost a day of events:
ALTER TABLE deadlines
  ADD COLUMN attempt_count int NOT NULL DEFAULT 0,
  ADD COLUMN next_retry_at timestamptz,
  ADD COLUMN last_error    text,
  ADD COLUMN response_code int;

-- Version four, after someone asked "did it actually fire?":
CREATE TABLE deadline_deliveries ( /* attempt history */ );

Every one of those changes follows an incident rather than a design review. Two workers double-processing a batch. A downstream outage that silently discarded a day of events. An operator asking whether a specific deadline fired, and nobody being able to answer.

The full list

What a complete implementation contains, roughly in the order teams discover each item.

Not every product needs every row. But the rows are not independent — a hosted page and an email image that disagree are worse than neither, so the clock authority has to be shared, which means it has to exist first.

The row that surprises people

Email is where build-it-yourself usually stops. Everything above it is ordinary backend work your team can do well. This one is a different discipline.

// The email requirement, in full.
//
// Email clients strip JavaScript, so a live countdown in an inbox
// has to be an image generated at open time. That means:
//
//   1. An HTTP endpoint that renders the current remaining time
//   2. Text layout and font rendering, server-side
//   3. Multi-frame GIF encoding, per request
//   4. Cache headers that defeat proxy caching without
//      hammering your own renderer
//   5. Enough throughput for a send to 50,000 recipients who
//      all open within the same hour
//
// Plus the same clock authority the rest of the system uses,
// or the email disagrees with the page.

The throughput requirement is the part that catches teams late. A send to fifty thousand recipients produces a burst of image requests concentrated in the hour after delivery, each needing a freshly rendered GIF because a cached one shows the wrong time. That is a rendering service with its own scaling characteristics, built to support a feature that is not your product.

When building it yourself is right

Often. The list above is long, but plenty of products genuinely need only the top of it.

The middle path

It is not all-or-nothing, and the split most teams land on is by visibility.

Keep what you have for internal deadlines

If your job runner already handles retries and dead letters, internal follow-ups and cleanup tasks are fine where they are. Moving them buys nothing.

Use the API where rendering is the requirement

Customer-facing countdowns — the ones that need a page, an embed, or an email GIF that all agree with each other — are where the cost of building is concentrated and the benefit of not building is largest. One POST /timers replaces the entire bottom half of that table.

Common questions

Related