Recurrence Cloud is a hosted scheduler: you register an app, describe when something should happen (cron expression or plain-English recurrence), and point it at where — a webhook URL it calls on every run. Integration is a single API call, and every delivery is signed and logged.
The project: Recurrence Cloud lives at recurrence.cloud — walkthrough-style docs start at Getting Started, and the full endpoint reference is in the API docs. The dashboard signup is at recurrence.cloud.
Core concepts
| Concept | What it is |
|---|---|
| App | Container for your webhooks, schedules, and API keys |
| API key | rc_live_... token that authenticates v1 API calls and signs deliveries |
| Schedule | When — a cron expression or human-friendly recurrence (“every 1 day at 09:00”) |
| Webhook | Where — URL, method, headers, and a default payload |
| Event | Data attached to a schedule, grouped by subject in deliveries |
| Schedule run | A receipt for every fire, including the response status |
Step 1: Create an app and an API key
Sign in to the dashboard, create an app, then generate an API key under your app → API Keys:
rawKey: rc_live_abcdef1234567890... # shown once — store it in your secretsThe raw key is only displayed at creation time; the database keeps a SHA-256 hash.
Step 2: Create schedule + webhook + event in one call
The composite endpoint is the fastest path from zero to a running schedule:
curl -X POST https://api.recurrence.cloud/api/v1/schedules/with-webhook \
-H "X-API-Key: rc_live_abcdef1234567890..." \
-H "Content-Type: application/json" \
-d '{
"appId": "clxyz_app_id",
"schedule": {
"name": "Daily Morning Report",
"frequency": "day",
"interval": 1,
"startTime": "09:00",
"timezone": "UTC",
"active": true
},
"webhook": {
"url": "https://example.com/webhooks/report",
"method": "POST",
"secret": "my-webhook-secret"
},
"event": {
"subject": "daily_report",
"payload": { "report_type": "morning_summary" }
}
}'Prefer raw cron? Set cronExpr instead of the frequency fields — the two forms are mutually exclusive:
{
"name": "Daily Morning Report",
"cronExpr": "0 9 * * *",
"timezone": "America/New_York"
}Step 3: Receive and verify the delivery
When a schedule fires, the worker merges the webhook’s default payload with its events, signs the body with HMAC-SHA256, and sends two extra headers:
X-Webhook-Signature: a3f2b8c9d1e4...
X-Signature-Algorithm: sha256
Verify it in your handler — Node.js:
const crypto = require('crypto');
app.post('/webhooks/report', (req, res) => {
const signature = req.headers['x-webhook-signature'];
const payload = JSON.stringify(req.body);
const expected = crypto
.createHmac('sha256', 'my-webhook-secret')
.update(payload)
.digest('hex');
if (signature !== expected) {
return res.status(401).json({ error: 'Invalid signature' });
}
console.log(req.body.scheduleName, req.body.firedAt, req.body.events);
res.json({ received: true });
});Python:
import hmac, hashlib
def verify_signature(payload: str, signature: str, secret: str) -> bool:
expected = hmac.new(
secret.encode(), payload.encode(), hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected, signature)The delivery body carries schedule metadata, events grouped by subject, and any webhook default payload merged at the top level:
{
"scheduleId": "clxyz_schedule_id",
"scheduleName": "Daily Morning Report",
"firedAt": "2026-05-21T09:00:00Z",
"organizationId": "clxyz_org_id",
"events": {
"daily_report": {
"id": "clxyz_event_id",
"subject": "daily_report",
"payload": { "report_type": "morning_summary" }
}
}
}Step 4: Monitor runs
Two views answer “did it fire?” and “did the other side accept it?”:
GET /api/schedules/:id/runs— the last 50 schedule runs with response statusGET /api/webhooks/:id/activity— the last 50 delivery attempts with duration and error details
Both are also visible in the dashboard, so on-call can check delivery health without touching the API.
Step 5: Dry-run before you trust it
The test-due endpoint is read-only — no records are written and nextFireAt is untouched. Ask “would this schedule fire at 9:30 tomorrow?” without waiting for tomorrow:
curl -X POST https://api.recurrence.cloud/api/v1/schedules/test-due \
-H "X-API-Key: rc_live_abcdef1234567890..." \
-H "Content-Type: application/json" \
-d '{ "dateTime": "2026-11-20T09:30:00Z" }'The response includes a match flag and a reason per schedule, plus the computed next fire time — useful for validating cron expressions against timezones before enabling a job.
Managing schedules over time
Everything is editable after creation. Use PATCH to adjust timing or swap the target webhook, active: false to pause without deleting, and DELETE to remove. Deactivating an app pauses all of its schedules and webhooks at once — handy for incident response.
Rate limits
| Tier | Requests/min | Webhooks/day |
|---|---|---|
| Free | 60 | 100 |
| Pro | 600 | 10,000 |
| Enterprise | Custom | Custom |
Responses carry X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.
Where to next
- Creating schedules — cron, recurrence text, and the one-call composite
- Webhooks & deliveries — payload shape and HMAC verification
- Monitoring & retries — activity trail and failure alerts
- Scheduling automated jobs with Recurrence Cloud — when to reach for a hosted scheduler at all