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
typeinside 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.