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 mail server of the sender controls its retry schedule, and it can stop before a long maintenance window ends.
• 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.

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.

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, use a cron validator such as crontab.guru.
• 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 the standard 5-field cron (min hour dom mon dow).
• 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.

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

Related guides#

• Endpoint Management
• Observability
• Troubleshooting