Scheduled Webhooks Reference

This reference describes the fields and execution rules for Phemeral scheduled webhooks.

Overview

A scheduled webhook is a saved HTTP request that Phemeral executes on a UTC cron schedule against a selected environment.

Each scheduled webhook is:

• configured from the project's Settings tab
• bound to one environment
• executed against that environment's oldest active domain
• routed to the environment's current deployment

For setup instructions, see Configure Scheduled Webhooks.

Cron Syntax

Scheduled webhooks use a UTC 6-field cron expression.

second minute hour day-of-month month day-of-week

Examples

All schedules are interpreted in UTC.

Field Reference

Method Values

Scheduled webhooks support these HTTP methods:

• GET
• POST
• PUT
• PATCH
• DELETE
• HEAD
• OPTIONS

Expected Status Codes

If Expected status codes is provided, Phemeral treats only those response codes as successful.

Examples:

• 200
• 200,201
• 200,201,202,204

If the field is left empty, any HTTP status code is accepted as successful.

Each status code must be between 100 and 599.

Time Window Rules

Starts at and Expires at must both be UTC ISO 8601 timestamps when provided.

Examples:

• 2026-05-01T00:00:00Z
• 2026-05-01T12:30:00+00:00

Rules:

• Timestamps must include timezone information.
• The timezone must be UTC.
• If both fields are set, starts_at must be earlier than expires_at.

Domain Resolution

Scheduled webhooks run only when the selected environment has at least one active domain.

Execution uses the environment's oldest active domain in canonical order.

Behavior:

• A new scheduled webhook cannot be saved without an active domain.
• If the active domain set changes, Phemeral resyncs the scheduled webhook.
• If no active domain is available, the webhook remains saved but cannot execute until a domain becomes active again.

Execution Semantics

When a scheduled webhook fires, Phemeral sends the configured request to the selected environment's active domain and relative path.

Because the request targets the environment rather than a fixed deployment:

• the webhook automatically follows new current deployments
• you do not need to update the webhook after each deploy
• runtime logs appear on whichever deployment handled that request

Validation Rules

Phemeral applies these validation rules when saving a scheduled webhook:

• name must be non-empty
• environment must belong to the selected project
• path must be a non-empty relative path
• schedule must be a valid UTC 6-field cron expression
• retries must be zero or greater
• expected status codes must be valid HTTP status codes
• starts_at and expires_at must be valid UTC timestamps

Runtime Visibility

Scheduled webhook requests are regular HTTP requests to your application. You can inspect them through:

• deployment runtime logs
• application logs emitted by the endpoint
• application-side effects such as writes, cache refreshes, or background work