Schedules

Cron, rate and one-time schedules with time zones, retries and dead letters.

A schedule runs something on a clock: call a webhook every five minutes, put a message on a queue on the first of the month, start a CI workflow at 03:00 Berlin time, run an app's job every night. When the call fails it is retried with backoff; when it keeps failing it goes to a dead-letter queue and an alarm fires. Every run is an invocation you can read: when it was due, each attempt, what the target answered, and the output.

Deutsche Cloud schedules work like Amazon EventBridge Scheduler schedules.

You want Use
A command in your app's image on a cron, kept by its machine the app's scheduled jobs
The same job with a time zone, retries, a dead-letter queue a schedule with an app job target
A workflow that runs on a schedule written in the repository on.schedule in the workflow file
A workflow started with inputs, retries or in a time zone a schedule with a CI target
Anything with an HTTP endpoint a schedule with an HTTP target
Work handed to your own consumers a schedule with a queue target

When it fires

Expression Fires
cron(0 3 * * *) five-field cron (minute hour day-of-month month day-of-week), in the time zone
rate(5 minutes) every 5 minutes (minute(s), hour(s), day(s)), counted from the start
at(2026-12-24T18:00:00) once, at that local time in the time zone
  • Time zone: any IANA name (Europe/Berlin, UTC, …). A cron reads that zone's wall clock. A time skipped when the clock jumps forward fires once, right after the jump; a time that happens twice when the clock goes back fires twice (so */15 keeps running every 15 real minutes).
  • Start and end date: nothing fires outside them.
  • Flexible window: with a window of 15 minutes, each invocation runs at a random moment in the 15 minutes after its time — to spread load.
  • Missed runs: if the scheduler was not running when a run was due (more than two minutes late), catchUp decides: latest (default) runs the most recent missed one once, none skips them, all runs each (at most 100, and none older than the maximum event age).
  • After an at() schedule has run, it stays (actionAfterCompletion: none) or is deleted (delete).

The console shows the next ten times as you type; GET /scheduler/api/preview does the same.

Targets

Target Does Counts as success
http POST (or PUT/PATCH/GET) to an https:// URL, signed a 2xx within the timeout
queue sends the input as a message to one of your queues the message is stored
ci starts a workflow file at a branch or tag (workflow_dispatch) the run is created
app_job runs one of an app's jobs on its machine, like Run now the job exits 0

Input (HTTP body, queue message, CI input values) may contain <ews.scheduler.scheduled-time>, <ews.scheduler.execution-id>, <ews.scheduler.attempt-number> and <ews.scheduler.schedule-name>, replaced on every attempt. Without an input, HTTP and queue targets send {"schedule", "invocationId", "scheduledTime", "attempt", "trigger"}.

An app job target runs a job you defined on the app's Jobs page. Turn the job's own schedule off (enabled: false) to run it only when the schedule fires it. The invocation waits for the job's exit code and output; a non-zero exit is a failure, retried like any other. The app's job history shows which runs a schedule asked for.

A CI target counts as delivered when the run starts. The run's conclusion is recorded on the invocation afterwards and counted in the TargetRunFailed metric, but a failed workflow is not re-run automatically.

Verifying an HTTP call

Every HTTP schedule has its own secret (Invocations → Reveal secret, or GET /scheduler/api/schedules/{name}/signing-secret). Each request carries these headers, each also under its name from before the rename, X-EWS-…, with the same value:

X-DCLOUD-Timestamp: 1763000000
X-DCLOUD-Signature-256: sha256=<hex HMAC-SHA256 of "<timestamp>.<body>" with the secret>
X-DCLOUD-Invocation-Id: 6f1c…          (the same on every retry: de-duplicate on it)
X-DCLOUD-Schedule-Name: nightly-report
X-DCLOUD-Scheduled-Time: 2026-11-13T02:00:00.000Z
X-DCLOUD-Attempt: 1
import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(req, rawBody, secret) {
  const ts = req.headers['x-dcloud-timestamp'];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // replay window
  const want = 'sha256=' + createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex');
  return req.headers['x-dcloud-signature-256']
    .split(',')
    .some((sig) => sig.length === want.length && timingSafeEqual(Buffer.from(sig), Buffer.from(want)));
}

After rotate (POST …/signing-secret/rotate) the old secret keeps signing for 24 hours and both signatures are sent, comma separated, so you can switch the receiver over without an outage.

URLs must be https:// on port 443 and resolve to public addresses; redirects are not followed.

Who it runs as

A schedule that calls Deutsche Cloud (queue, CI, app job, or a dead-letter queue) acts as an IAM role you give it. Giving it the role needs iam:PassRole on that role. Every invocation is then authorized as the role — queue:SendMessage on the queue, ci:StartWorkflow on the repository, deploy:RunJob on the app — and recorded in the audit log under assumed-role/<role>. Take the permission away from the role and the next invocation fails with AccessDenied, visibly.

A minimal role policy for a schedule that sends to reports and dead-letters to reports-dlq:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "queue:SendMessage",
      "Resource": ["rn:ews:de1:<org-id>:queue:queue/reports", "rn:ews:de1:<org-id>:queue:queue/reports-dlq"]
    }
  ]
}

When it fails

  • Retries: up to retryMaxAttempts (0–20, default 3) more attempts, the first after retryBackoffSeconds (default 30), doubling each time (±20 %, at most 15 minutes).
  • Retried: HTTP 5xx, 429 and 408, timeouts, connection errors, a job run that failed, timed out or got no machine. Not retried: other 4xx, AccessDenied, a target that no longer exists (TargetMissing), an invalid workflow.
  • Maximum event age (maxEventAgeSeconds, 60 s – 24 h): no attempt starts later than this after the scheduled time.
  • Dead-letter queue: an invocation that failed for good is sent there as JSON — {schedule, scheduleRn, invocationId, scheduledTime, attempts, errorCode, error, target}.
  • Failure alarm: failureAlarm: {notifyEmails: [...]} creates an alarm on this schedule's InvocationsFailed (sum > 0 over a minute) under Monitoring → Alarms; it is deleted with the schedule.

Deleting a schedule's target (the queue, the app, the job, the role) does not stop the schedule: its invocations fail as TargetMissing, which you see and are alarmed on.

Seeing what happened

  • Invocations (console, dcloud scheduler schedules invocations <name>): status (pending, running, waiting for a job run, retry_wait, succeeded, failed, dead_lettered, dropped), attempts, the target's answer and output, links to the job run or CI run.
  • Log: one stream per invocation, every attempt and its answer (GET /scheduler/api/schedules/{name}/invocations/{id}, or Monitoring logs with resourceType=schedule).
  • Events: created, changed, each finished invocation, missed runs.
  • Metrics in namespace EWS/Scheduler, dimension ScheduleName: InvocationAttempts, InvocationsSucceeded, InvocationsFailed, InvocationsDeadLettered, InvocationsDropped, TargetRunFailed — chart them and alarm on them like your own metrics.

Guarantees

  • One invocation per scheduled time, even with several scheduler workers running.
  • At-least-once delivery: an attempt can reach the target twice if the worker dies after the target accepted it and before the result was written. Use X-DCLOUD-Invocation-Id (HTTP), the dcloud-invocation-id message attribute (queues; on a FIFO queue it is the deduplication id) to de-duplicate. An app job attempt never starts twice.
  • Times are accurate to about a second; claims are made up to a minute ahead and handed to the worker queue to start at the due time.

API, CLI, Terraform

dcloud scheduler schedules create --name nightly-report --expression 'cron(0 3 * * *)' \
  --timezone Europe/Berlin --role-name reports-scheduler \
  --target '{"type":"queue","queueName":"reports"}' --dead-letter-queue reports-dlq
dcloud scheduler schedules invoke nightly-report          # run it now
dcloud scheduler schedules invocations nightly-report
resource "dcloud_schedule" "nightly" {
  name       = "nightly-report"
  expression = "cron(0 3 * * *)"
  timezone   = "Europe/Berlin"
  role_name  = dcloud_iam_role.reports.name
  target     = jsonencode({ type = "queue", queueName = "reports" })
}

Limits: 500 schedules per organization, one minute between runs at the least, 64 KiB input, 1 000 invocations kept per schedule (30 days).

Did this page help you?