When Underlayer dispatches a task or cron job, it makes an HTTP request to the URL you configured. Understanding how delivery and retries work helps you build reliable integrations.

Delivery semantics

Underlayer aims for at-least-once delivery. In rare failure scenarios (e.g. a crash mid-flight) the same call may be retried even if the target already received it. Design your endpoints to be idempotent where possible.

What counts as success

A dispatch is considered successful when your endpoint returns any 2xx HTTP status code (200–299). Any other status code (including 3xx redirects) is treated as a failure and triggers a retry.

Timeouts

Each dispatch attempt has a 30-second timeout. If your endpoint does not respond within that window, the attempt is marked as timed out and counts as a failure. Make sure long-running processes return a 2xx quickly and do the heavy work asynchronously.

Retry policy

On failure, Underlayer retries the dispatch with exponential backoff:

• 1st retry after ~30 seconds
• 2nd retry after ~2 minutes
• 3rd retry after ~10 minutes
• Additional retries follow the same progression

The maximum number of retries is determined by your organization plan. For cron jobs, each occurrence is treated independently, so a failed run does not prevent the next scheduled occurrence.

Request headers

Every dispatch includes these headers in addition to any custom headers you configure:

• User-Agent: Underlayer/1.0 — always present.
• X-Underlayer-Task-Id: <uuid> — present only on one-off task dispatches.
• X-Underlayer-Execution-Id: <uuid> — present only on cron job execution dispatches.
• X-Underlayer-Attempt: <n> — always present. 1 on the first attempt, 2 on the first retry, and so on. Use this to detect and safely handle duplicate deliveries.

Failure alerts

You can configure alerts to notify you when a dispatch fails repeatedly. Go to Alerts in the dashboard to set up email or webhook notifications.