Countdown Timer API vs Posthook

Two models of the same moment

// Posthook: schedule a callback for a moment in the future.
await posthook.post("/hooks", {
  path: "/api/expire-invitation",
  postAt: expiresAt.toISOString(),
  data: { invitationId: invitation.id },
});

// Straightforward and durable. Between now and postAt there is
// no object to read, nothing to pause, and nothing to render.

// Countdown API: the deadline is the resource.
const { data: timer } = await call("/timers", {
  method: "POST",
  headers: { "Idempotency-Key": `invite_${invitation.id}` },
  body: JSON.stringify({
    name: `Invitation ${invitation.id}`,
    type: "fixed",
    deadline_at: expiresAt.toISOString(),
    publish: true,
  }),
});

// Fire early as well as at zero — one rule per milestone.
for (const [name, seconds] of [["1 day left", 86400], ["Expired", 0]]) {
  await call(`/timers/${timer.id}/webhook-rules`, {
    method: "POST",
    body: JSON.stringify({
      name,
      webhook_destination_id: destinationId,
      condition: seconds
        ? { field: "remaining_seconds", operator: "less_than_or_equal", value: seconds }
        : { field: "status", operator: "equals", value: "ended" },
    }),
  });
}

The Posthook version is shorter, and for a single callback that is a genuine advantage — fewer concepts, less to hold in your head. The countdown version costs an extra call because it separates the deadline from the things that watch it, which is what makes “also tell me a day beforehand” a rule rather than a second schedule you have to keep in sync.

Side by side

Rules versus one hook per moment

The design difference that matters most in practice is how you express “tell me at several points along the way”.

With scheduled hooks

Each milestone is its own scheduled callback, computed at creation. If the deadline later moves, you cancel and recreate all of them — and any you forget will fire at the old time.

With rules on a timer

Milestones are conditions attached to one deadline: one hour remaining, seventy-five percent through, ended. Move the deadline with a single PATCH and every rule re-evaluates against the new one, because they were never separate schedules to begin with.

The part neither scheduler does

When Posthook is the better choice

Put plainly: if you would never render the deadline, Posthook does the scheduling job with fewer moving parts. The case for a countdown API begins at the point someone asks to see the clock.

Common questions

Related