Maintenance Windows

Use this guide to set a scheduled pause for an endpoint.

Purpose#

Use this guide to:

• Schedule an endpoint pause for a backend deployment or for maintenance.
• Use a UTC cron expression for recurring downtime.
• Know the effect of a scheduled pause on a manual pause.

How maintenance windows operate#

A maintenance window pauses an endpoint for a fixed period on a recurring schedule. Use a maintenance window for these tasks:

• A regular backend deployment window, such as 30 minutes at 3 AM each night.
• The scheduled maintenance of a downstream system.
• A quiet period for a test or a data migration.

During an active maintenance window:

• PayloadRelay rejects a webhook request with HTTP 503 Service Unavailable.
• Email ingestion receives SMTP 451. The PayloadRelay mail server keeps the email and sends it again for a maximum of 5 days. If the window is longer, the mail server returns the email to the SMTP envelope sender.
• A rejected webhook request and a temporarily rejected email create no request activity row.
• The endpoint interface shows the standard paused state and the resume countdown.

Before you start#

• Make sure that you can edit the endpoint.
• Knowledge of the cron syntax. This guide gives examples.

Procedure#

1. Enable maintenance windows#

1. Open the endpoint edit page.
2. Select the Details tab.
3. Open the Maintenance window section.
4. Enable Maintenance window.

2. Configure the schedule#

Cron format:

* * * * *
│ │ │ │ │
│ │ │ │ └── Day of week (0–6, Sunday=0)
│ │ │ └──── Month (1–12)
│ │ └────── Day of month (1–31)
│ └──────── Hour (0–23)
└────────── Minute (0–59)

3. Cron expression examples#

All the times are in UTC.

If the day-of-month field and the day-of-week field both have a value, the window starts only on a day that matches the two fields. A standard Unix cron starts on a day that matches one of the two fields. For example, 0 3 13 * 5 starts on a Friday the 13th only.

You can also use one of these macros. Each macro starts at 00:00 UTC, or at minute 0 for @hourly:

PayloadRelay examines a cron expression when you save it. PayloadRelay rejects an invalid pattern with 400 Bad Request.

4. Timezone#

A maintenance window always uses UTC. Before you enter the cron expression, convert the local schedule to UTC. UTC has no daylight-saving transition.

5. Understand manual-pause interaction#

A maintenance window never makes an existing manual pause shorter. If a manual pause ends after the scheduled window, PayloadRelay keeps the later resume time. If the maintenance window is longer, the endpoint stays paused until the window ends.

If you disable Maintenance window during a scheduled pause, that pause ends when you save. A manual pause stays until its end time, or until you resume the endpoint. If you save a different duration during a scheduled pause, a later disable does not end that pause. The pause then continues until its end time.

When you enable a maintenance window, PayloadRelay examines the last hour. If a window started in that hour, the endpoint pauses for the remaining time of that window. A window that started more than 1 hour before does not pause the endpoint.

6. Monitor maintenance windows#

In the endpoint details view:

• The Next maintenance timestamp shows when the next scheduled window starts.
• During an active window, the endpoint shows the paused state and the remaining time.

In Request activity:

• Activity does not show the webhook requests and the emails that PayloadRelay rejects during a maintenance window. A scheduled pause creates no Request activity row and no audit event. To see the pause, use the endpoint pause state, the resume countdown, and the Next maintenance timestamp.

Expected result#

• A maintenance window fires on schedule in UTC.
• A webhook request during the window receives HTTP 503. An inbound email receives SMTP 451. The two responses create no request activity row.
• After the duration ends, the endpoint resumes automatically.
• The Next maintenance value in the interface updates after each window fires.

Common issues and fixes#

• The window does not fire: make sure that the cron expression uses UTC. To examine the schedule, read Next maintenance in the editor. A cron validator such as crontab.guru accepts 5 fields only. When both day fields have a value, crontab.guru uses a day that matches one of them, but PayloadRelay needs a day that matches both.
• The duration is too short: if the maintenance continues after the window, make the duration longer.
• A daylight-saving problem: use UTC, or select a time outside the transition.
• A manual pause is longer than you expect: a scheduled window never makes a manual pause shorter. To end it earlier, resume the endpoint manually.

Cron validation#

PayloadRelay examines a cron expression when you save it:

• Use 5 fields (min hour dom mon dow), or 6 fields with the seconds first. You can also use a macro from the list above.
• Each field must be valid (*, */n, n, n-m, n,m).
• A numeric range must stay in the limits, for example, the hour from 0 to 23.
• The editor does not accept the W form or the L-n form in the day-of-month field. Use a fixed day, a range, a list, or L.

An invalid expression returns 400 Bad Request with an error that gives the detail.

Related guides#

• Endpoint Management
• Observability
• Troubleshooting