Scheduling

The schedule object in an event says when it fires. It's a tagged union on kind — one of three shapes.

All times are ISO-8601 and must be UTC (a trailing Z); numeric offsets like +01:00 and zone-less local times are rejected.

One-shot

Fires once, then the event is done.

{ "kind": "oneshot", "fireAt": "2026-07-04T15:30:00Z" }

• fireAt — when to fire.

A fireAt in the past is accepted and fires on the next poll (effectively immediately) — convenient for testing, so guard against it if that's not what you want.

Interval

Fires repeatedly on a fixed period.

{ "kind": "interval", "everySeconds": 3600, "startAt": "2026-07-04T15:00:00Z" }

• everySeconds — the period, in seconds. Must be > 0 and at most 31622400 (366 days). There's no minimum floor beyond positive, but keep it sane for your target.
• startAt (optional) — the first fire. Omit it and the first fire is now + everySeconds; each subsequent fire is everySeconds after the last.

Cron

Fires on a cron expression — for calendar-aligned schedules ("every weekday at 09:00").

{ "kind": "cron", "expression": "0 9 * * 1-5", "timezone": "Europe/London" }

• expression — a standard 5-field expression minute hour day-of-month month day-of-week. An optional leading 6th field adds seconds (second minute hour dom mon dow). Named shortcuts work too: @hourly, @daily, @weekly, @monthly, @yearly, @weekdays, @weekends; as do ranges (1-5), steps (*/15), lists (1,15), L, #, and JAN–DEC / SUN–SAT aliases. (Parsed by cron-parser.)
• timezone (optional) — an IANA zone name like Europe/London or America/New_York.

Set timezone explicitly. When omitted, the expression is evaluated in the server's local timezone, not UTC — so 0 9 * * * without a timezone may not fire at 09:00 where you expect. Always pass one for cron schedules that care about wall-clock time.

Limits

• Payload — up to 1 MB (decoded), via payloadBase64 on the event.
• Interval — at most 366 days per period.
• Horizon — no cap on how far ahead a one-shot or cron can be scheduled.
• Idempotency — an optional idempotencyKey (≤200 chars) on create makes a repeated POST return the existing event rather than a duplicate.

Where it goes next

The schedule decides when; the target decides where — a webhook or an email. Both pair with any of the three schedule kinds.