How to integrate scheduling with Recurrence Cloud

Wire your app into Recurrence Cloud — create an app, mint an API key, schedule a recurring webhook with one API call, verify signed deliveries, and monitor run history.

, updated

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 secrets

The 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 status
  • GET /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