DOCS · CORE WORKFLOWS

Events & Batching

Attach event definitions to schedules, group them by subject, and design batched series that retry atomically.

An event is a named, structured payload attached to a schedule: a subject (the grouping key) and a free-form payload. Schedules carry the when; events carry the what.

Create events

The first event usually comes along in the with-webhook composite. Attach more whenever — same API key, no redeploy:

curl -X POST https://api.recurrence.cloud/api/events \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{ "scheduleId": "<schedule id>", "subject": "billing-run-11", "payload": { "type": "billing.invoices", "period": "2026-01" } }'

Read them with GET /api/events/by-schedule/:scheduleId, update a schedule’s set any time.

How batches arrive

At fire time, events on the schedule are collected and grouped by subject:

  • One event → a flat entry: { id, subject, scheduleId, scheduleName, data }
  • Several events, same subject → grouped: { subject, count, events: [ … ] } — one webhook

So a billing run with three events (billing.rollup, billing.invoices, billing.notifications) under subject billing-run-11 arrives as one POST, processed in order:

for (const group of batch.events) {
  const events = Array.isArray(group.events) ? group.events : [group];
  for (const event of events) {
    switch (event.data.type) {
      case "billing.rollup":        /* … */ break;
      case "billing.invoices":      /* … */ break;
      case "billing.notifications": /* … */ break;
    }
  }
}

Choosing subject boundaries

The subject is your unit of work decision:

Subject pattern Use case
tenant-acme Multi-tenant SaaS — one delivery per tenant, respecting their rate limits
run-2026-01-23 One daily batch that completes or retries as one transaction
customer-sync All sync payloads for one receiver in one pass

Design conventions

  • type inside the payload ("type": "billing.rollup") lets receivers dispatch without extra fields — the envelope already carries identity/id/subject.
  • One subject per logical run so batch retries are atomic (a partially-processed batch can be replayed as a whole).
  • Put ordering-dependent data in the payload; event order within a batch is stable, and your dispatcher decides parallelism.
  • Batches and retries compose: if attempt 1 times out mid-series, attempt 2 redelivers the same batchId — dedup on it.

Next: Monitoring & retries — watching every attempt, and what happens on failure.