Timers

A timer lives on Bankroll instead of in your process. Set one with a meta and a number of minutes, and when it fires Bankroll delivers timer.fired with that meta to your webhook route, once. It is for what your server must do when nobody is asking it: a no-show deadline, a round that ends on the clock. Your server keeps no timer and runs no cron.

Setup

Your exact origin must be Bankroll Verified, and your webhook route must be in place: a fired timer is delivered the same way as a reference event, signed with BANKROLL_WEBHOOK_SECRET.

Set a timer

createTimer is on @joinbankroll/sdk/server and takes the same { origin } as createManagedReference.

import { createTimer } from "@joinbankroll/sdk/server";

const { id, at } = await createTimer(
  { meta: { kind: "deadline", roundId: round.id }, firesInMinutes: 15 },
  { origin: "https://acme.example" },
);
await rounds.setDeadline(round.id, { timerId: id, at });

Field	Notes
`meta`	Your own routing data, plain JSON up to 4 KiB, echoed verbatim on the event. Put in it what you need to find the subject again.
`firesInMinutes`	Whole minutes from now, 1 to 43200 (thirty days). Bankroll fires timers once a minute, so a timer is set to the minute.
`id`	The timer’s id, on the event as well.
`at`	The time Bankroll recorded, ISO 8601.

A timer is not cancelled: when it fires, look at what it names and decide whether there is still anything to do. createTimer throws TimerError with a code:

Code	Meaning
`unauthenticated`	No usable app key, or Bankroll refused the credential.
`app_not_verified`	The origin serves no Bankroll-signed manifest.
`webhook_not_provisioned`	The app was verified before webhooks existed; re-sign it.
`invalid_argument`	`meta` is not plain JSON, or `firesInMinutes` is out of range.
`unavailable`	Bankroll could not be reached; nothing was created.

Handle the event

timer.fired carries id, meta and at. The route hands it to onFired; handle it idempotently, since a delivery can be retried.

// src/app/api/bankroll/webhook/route.ts
import { bankrollWebhook, type TimerFired } from "@joinbankroll/sdk/webhooks";

async function onFired(event: TimerFired) {
  if (event.meta.kind !== "deadline") return;
  const round = await rounds.find(event.meta.roundId);
  if (round.status === "waiting") await rounds.forfeit(round.id);
}

export const POST = bankrollWebhook({ onConfirmed, onExpired, onFired });

Under the mock

With BANKROLL_MOCK=1 outside production nothing reaches Bankroll: the timer is set locally and delivers timer.fired to your route itself, unsigned, when it fires.

Get Started

Guides

Reference

Bankroll Verified

Helpers

Changelog

Setup

Set a timer

Handle the event

Under the mock

​Setup

​Set a timer

​Handle the event

​Under the mock

Setup

Set a timer

Handle the event

Under the mock