Six reporters can deliver a job's outcome: Sentry, email (SMTP), an arbitrary shell command, an HTTP webhook (Slack-compatible by default), end-to-end encrypted push to paired devices, and the Windows Event Log. Configure them under the report block of the onFailure, onPermanentFailure, onSuccess, and onLate hooks.

This page documents every reporter option, its type and default, the secret-resolution rules, the jinja2 template variables, and the environment variables passed to the shell reporter.

Each job has four reporting hooks, each with the same report block schema:

All four hooks accept the identical report block (sentry, mail, shell, webhook, push, eventlog). The default report configuration applies independently to each hook (_REPORT_DEFAULTS is deep-copied into each), so configuring one hook does not affect the others.

onLate's defaults differ in wording only, because an SLA breach has no run outcome to describe:

• Its default mail subject is Cron job '{{name}}' is overdue ({{sla_check}}).
• Its default body names the check, threshold, observed value, and last success.
• Its default webhook body wraps the same text in the Slack-compatible {"text": ...} shape.
• Its default sentry fingerprint is ["cronstable", "sla", "{{ name }}"], which groups breaches apart from run failures.

A run that is deliberately terminated to make way for a newer instance (concurrencyPolicy: Replace) is not treated as a failure and is neither reported nor retried. See concurrency and timeouts.

For any given hook, cronstable always invokes all six reporters concurrently (asyncio.gather with return_exceptions=True). A reporter that is not configured returns early and does nothing:

• Sentry returns if no dsn source is set.
• Mail returns if to or from is unset.
• Shell returns if command is unset (None).
• Webhook returns if no url source is set.
• Push returns if enabled is false (the default).
• Event Log returns if enabled is false (the default), and again on any platform that is not Windows.

An exception raised by one reporter is logged at ERROR level (with traceback) and does not prevent the other reporters from running, nor does it propagate to the scheduler.

subject, body (mail), body and each fingerprint entry (sentry), and body (webhook) are jinja2 templates. Each distinct template source is compiled once and cached in a bounded LRU (256 sources), so the same template string is not recompiled on every report.

These variables are available when rendering any report template:

An onLate dispatch renders the same variable set with the run-shaped fields empty: success is False, fail_reason is sla: <check> breached, and stdout/stderr/exit_code/started_at/run_id are None. It adds four breach variables: sla_check, threshold_seconds, observed_seconds, and last_success_at. host and schedule are still populated, because they describe the job even when it did not run. See late-run detection.

To capture output for reports, enable captureStderr (on by default), captureStdout, or both. See output capturing.

The mail subject, also prepended to the sentry body, uses:

Cron job '{{name}}' {% if success %}completed{% else %}failed{% endif %}

The default body (DEFAULT_BODY_TEMPLATE) prints the fail reason (when set) followed by captured stdout/stderr, or (no output was captured):

{% if fail_reason -%}
(job failed because {{fail_reason}})
{% endif %}
{% if stdout and stderr -%}
STDOUT:
---
{{stdout}}
---
STDERR:
{{stderr}}
{% elif stdout -%}
{{stdout}}
{% elif stderr -%}
{{stderr}}
{% else -%}
(no output was captured)
{% endif %}

The default sentry body concatenates the default subject template, a newline, and the default body template.

Sends an email over SMTP with aiosmtplib. Reporting is enabled only when both to and from are set; otherwise the mail reporter returns without sending.

In the strictyaml schema, from and to are required keys when a mail block is present (they accept an empty value, mapping to None), while the remaining keys are optional. Behaviorally, mail reporting is skipped unless both resolve to a nonempty value.

Notes on behavior:

• validate_certs defaults to true. Unless you set validate_certs: false, connections to servers with self-signed or otherwise untrusted certificates fail.
• The reporter sets an RFC 5322 Date header (email.utils.format_datetime(datetime.now(timezone.utc))), for example Wed, 18 Jun 2026 12:34:56 +0000, not ISO-8601.
• Empty-body success emails are skipped. On a success report, if the rendered body is empty after stripping whitespace, no email is sent. (Failure reports are sent even with an empty body.)
• The reporter always closes the SMTP connection, even if STARTTLS, login, or sending raises, so a misbehaving server cannot leak one connection per report.
• html: true uses set_content(body, subtype="html"), which sets the correct charset and transfer-encoding for non-ASCII HTML.

Minimal failure-mail example:

jobs:
  - name: backup
    command: /usr/local/bin/backup.sh
    schedule: "0 3 * * *"
    captureStderr: true
    onFailure:
      report:
        mail:
          from: [email protected]
          to: [email protected], [email protected]
          smtpHost: 127.0.0.1
          smtpPort: 25
          starttls: false
          validate_certs: false

HTML success mail with login (password from environment):

jobs:
  - name: report-build
    command: render-report
    schedule: "@reboot"
    captureStdout: true
    onSuccess:
      report:
        mail:
          from: [email protected]
          to: [email protected]
          smtpHost: smtp.example.com
          smtpPort: 587
          starttls: true
          username: cron
          password:
            fromEnvVar: SMTP_PASSWORD
          html: true
          subject: "Build report for {{ name }}"
          body: "{{ stdout }}"

Captures a message to Sentry with sentry-sdk. Reporting is enabled only when a dsn source resolves to a value; otherwise the reporter returns early.

Notes on behavior:

• The reporter initializes the Sentry client once and caches it. It rebuilds the client only when dsn, environment, or maxStringLength changes.
• maxStringLength: 0 sets no limit, so Sentry's own default applies.
• In addition to any extra you supply, cronstable always attaches job, exit_code, command, shell, and success to the event's extra context. Your extra map is merged on top of these.
• Capture uses an isolated scope (sentry_sdk.new_scope()); the reporter applies the configured fingerprint and extras per event.

Fingerprint merge semantics: fingerprint is a replace-not-append setting. When a defaults block or a job supplies its own fingerprint, it overrides the default list entirely instead of being concatenated onto the three default entries. This is a deliberate special case in the config merge, so you can customize Sentry issue grouping.

All other list-valued options merge by concatenation; environment (the job env list) merges by key. See includes, defaults, and multi-file config.

Example:

jobs:
  - name: ingest
    command: run-ingest
    schedule: "*/5 * * * *"
    captureStderr: true
    onFailure:
      report:
        sentry:
          dsn:
            fromEnvVar: SENTRY_DSN
          level: warning
          environment: production
          fingerprint:
            - ingest-job
            - "{{ name }}"
          extra:
            datacenter: dc1
            shard: 3

Runs a user-supplied command, passing job state through CRONSTABLE_* environment variables.

Execution model:

• If command is a list, the daemon runs it directly with asyncio.create_subprocess_exec (no shell).

• If command is a string and shell is set (on POSIX the default /bin/sh applies), the daemon runs it as [shell, "-c", command] with asyncio.create_subprocess_exec. On Windows a cmd/cmd.exe shell instead hands the string to asyncio.create_subprocess_shell (%ComSpec% /c).

• If command is a string and shell resolves to a falsy value (such as shell: ""), the daemon passes the string to asyncio.create_subprocess_shell, which runs it through the system default shell. This is the Windows default, where the empty shell makes the string run through the native command processor (cmd.exe through %ComSpec%).

  To use PowerShell or another interpreter on Windows, set shell: explicitly, or pass command as a list to bypass the shell entirely. See running on Windows.

• The reporter does not fail the job. A failure to launch the command is logged with a traceback, and the reporter returns. A nonzero exit code from the command is logged at ERROR level, without a spurious traceback.

• The reporter command runs in its own process group. If it exceeds timeout (default 60 seconds), the daemon stops it together with anything it spawned, so an unresponsive notify script cannot stall the daemon's job-completion handling.

The shell command inherits the full environment of the cronstable process, plus the following variables describing the job outcome:

Truncation: stdout and stderr can be large, and there are OS limits on argument/environment sizes. cronstable truncates each stream to a maximum of 16 KiB (1024 * 16) when either stream individually, or the two combined, exceeds that limit. CRONSTABLE_STDERR_TRUNCATED / CRONSTABLE_STDOUT_TRUNCATED indicate per-stream whether truncation occurred.

Example:

jobs:
  - name: ping-job
    command: do-work
    shell: /bin/bash
    schedule: "* * * * *"
    onFailure:
      report:
        shell:
          shell: /bin/bash
          command: echo "job $CRONSTABLE_JOB_NAME failed with code $CRONSTABLE_RETCODE"

This POSIX-shaped example (a /bin/bash shell and $VAR syntax) won't run as written on Windows. There, either leave shell unset (the command runs through cmd.exe, with %VAR% syntax) or set shell: to a PowerShell path. See running on Windows.

List form (no shell):

        shell:
          command:
            - /usr/local/bin/notify
            - --job
            - "failed"

Sends an HTTP request (POST by default) to a configured URL, with a jinja2-templated body. The default body is a JSON {"text": ...} payload carrying the same subject-plus-body text as the default mail/sentry templates. Slack, Mattermost, and Microsoft Teams incoming webhooks accept that shape with no further configuration.

Override body for services expecting a different shape. For example, Discord expects {"content": ...}, and ntfy takes a plain-text body. Reporting is enabled only when a url source resolves to a value; otherwise the reporter returns early.

The default body template JSON-encodes the rendered text with jinja2's tojson filter, so job output containing quotes, newlines, or non-ASCII text always produces valid JSON:

{"text": {% filter tojson %}<default subject>
<default body>{% endfilter %}}

Notes on behavior:

• A response status of 400 or above is logged at ERROR level, with up to 1 KiB of the response text. As with all reporters, it neither fails the job nor blocks the other reporters. The report dispatcher logs connection errors and timeouts the same way.
• The webhook URL is never written to the logs, in either the success or the error path.

Slack (or Mattermost/Teams) failure notification:

jobs:
  - name: backup
    command: /usr/local/bin/backup.sh
    schedule: "0 3 * * *"
    captureStderr: true
    onFailure:
      report:
        webhook:
          url:
            fromEnvVar: SLACK_WEBHOOK_URL

Discord (custom body shape), with the URL read from a mounted secret file:

        webhook:
          url:
            fromFile: /etc/secrets/discord-webhook
          body: >-
            {"content": {% filter tojson %}Cron job '{{ name }}'
            {% if success %}completed{% else %}failed:
            {{ fail_reason }}{% endif %}{% endfilter %}}

ntfy (plain-text body, priority in a header):

        webhook:
          url:
            value: https://ntfy.sh/my-alerts
          contentType: text/plain
          headers:
            Title: cronstable job failure
            Priority: high
          body: "Cron job '{{ name }}' failed: {{ fail_reason }}"

headers values are sent verbatim; only body is a jinja2 template.

Sends an end-to-end encrypted alert to every paired device through a hosted relay. The payload is sealed to each device's public key, under the sealing suite the device registered at pairing (see push notifications), before it leaves the daemon, so the relay forwards ciphertext it cannot read. The companion app decrypts and renders the notification on the device. Reporting occurs only when enabled is true; otherwise the reporter returns early.

It requires the following, enforced at config load:

• The push extra (pip install "cronstable[push]").
• A daemon-global push: section naming the relay and the device-registry storage.

It also refuses a routable web listener with no web.authToken, because the pairing endpoints would be unauthenticated.

The alert goes to every paired device at once, so an unreachable relay costs one push.relay.timeout in total rather than one per device. Pairing, sealing suites, storage, size limits, and the trust model are documented on push notifications.

Example:

push:
  relay:
    url: https://relay.example.net/v1/notify
  devicesFile: /var/lib/cronstable/devices.json

jobs:
  - name: backup
    command: /usr/local/bin/backup.sh
    schedule: "0 3 * * *"
    captureStderr: true
    onFailure:
      report:
        push:
          enabled: true
          priority: time-sensitive

Notes on behavior:

• This block only opts a hook in. The relay endpoint and the paired-device registry live in the daemon-global push: section (see the push section).
• Unlike the other reporters, there is no template. The sealed payload is a fixed JSON shape (name, kind, host, timestamp, run context, optional log tail) that the companion app renders after decrypting. See what an alert contains.
• The alert fans out to every paired device. A sealing failure or relay outage is logged per device and, like every reporter error, neither fails the job nor blocks the other reporters. With no device paired, the alert is dropped with a warning naming the pairing endpoint.
• The same block under notify.report, described later, pushes daemon events: directed acyclic graph (DAG) failures, approval gates, and leadership/quorum changes.

Writes each outcome to the Windows Event Log. Windows only: on any other platform the reporter returns early, and the configuration load warns once, naming every hook that enabled it. It needs no extra and no dependency.

onFailure:
  report:
    eventlog:
      enabled: true
      source: cronstable
      includeOutput: false

Notes on behavior:

• Unlike the other reporters, there is no template. A record is a stable event ID plus a fixed, ordered set of insertion strings, because consumers key on the ID and the field positions. A free-text override of either is a contract this reporter cannot keep. For prose, use the shell or webhook reporter.
• Writes go to a background thread, so a busy Event Log service can never delay a job's completion handling. A graceful shutdown drains the queue with a five-second bound. A hard kill drops whatever it still held.
• includeOutput is off by default, the opposite of push's includeLogTail, because every local account can read the Application log, whereas a push payload is sealed to a paired device's key.

See Windows Event Log for the event-ID table, the insertion-string positions, the "description cannot be found" preamble, and the optional source registration.

The four preceding hooks report on job runs. A separate top-level notify: block reports on daemon and orchestration events that are not job runs, over the same six reporters:

The block carries a report block (the identical sentry / mail / shell / webhook / push / eventlog schema documented earlier) and an optional events allowlist. To report on every event, omit events; to filter, list a subset. A config holds at most one notify: block (like web:), and it is picked up on a reload.

notify:
  events:              # optional; default is every event
    - dag_failure
    - quorum_loss
  report:
    webhook:
      url:
        fromEnvVar: OPS_WEBHOOK_URL

Because a daemon event has no job run, notify's default templates key on the event instead of the completed/failed job wording. The template variables are:

The default mail subject is cronstable {{ event }}: {{ subject }}, and the default body is {{ message }}. The default webhook body wraps them in the Slack-compatible {"text": …} shape, and the default sentry fingerprint is ["cronstable", "{{ event }}", "{{ name }}"], which groups events by type and subject. Override any of them exactly as for a job report.

Notes:

• DAG task runs are reported by the job hooks, not notify:. A DAG task is a job invocation, so its own onFailure/onSuccess hooks fire on its runs, whether inherited from the file's defaults: or set per task. notify.dag_failure fires once for the whole DAG run reaching failed, naming the failed tasks.
• Regaining leadership or quorum is not paged. leader_change fires on both acquire and lose (differentiated by is_leader), but a quorum recovery is logged, not notified. The loss is the alert.
• Notifications are fire-and-forget and never block the scheduler, cluster loop, or a DAG advance. A reporter failure is logged and dropped.

The mail.password, sentry.dsn, and webhook.url options are secret blocks with three mutually exclusive sources. Each is an optional key accepting a string or empty value:

The first source that is set wins (value, then fromFile, then fromEnvVar). If none is set, the reporter treats the secret as absent (Sentry: disabled; mail: no login).

A set source that resolves empty (such as a fromEnvVar naming an unset or empty variable) skips the report with an error naming the config key; no environment-variable name is logged for any reporter.

        sentry:
          dsn:
            fromFile: /etc/secrets/sentry-dsn
        mail:
          from: [email protected]
          to: [email protected]
          smtpHost: 127.0.0.1
          username: cron
          password:
            fromEnvVar: SMTP_PASSWORD

• Push Notifications: the end-to-end encrypted channel behind the push reporter, and how devices are paired
• Configuration Reference
• Failure Detection and Retries
• Late-Run Detection: the sla: thresholds behind the onLate hook
• Output Capturing
• Metrics with statsd
• Resource Monitoring
• Includes, Defaults, and Multi-File Config
• Running on Windows