Schedule HTTP Callbacks with Cron Expressions

The Cron Service lets you schedule recurring HTTP callbacks using standard cron expressions. Instead of running your own scheduler infrastructure, define a job and the service will POST to your endpoint on schedule.

What You'll Learn

  • How to create a scheduled job that fires every 5 minutes
  • How to view execution history and detect failures
  • How to trigger a manual run and configure overlap policies

Prerequisites

Before you start: You need an API key. Follow the Platform Quick Start to get one.

  • curl (or any HTTP client)
  • A valid API key in the X-API-KEY header
  • A publicly accessible HTTP endpoint to receive callbacks

Step 1: Create a Scheduled Job

Define a job with a cron expression, target URL, and optional headers/body. The example below fires every 5 minutes.

bash
curl -X POST /api/cron-service/jobs \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your-api-key" \
  -d '{
    "name": "Refresh Cache",
    "cronExpression": "*/5 * * * *",
    "timezone": "UTC",
    "targetUrl": "https://api.mycompany.com/internal/cache/refresh",
    "httpMethod": "POST",
    "headers": { "Authorization": "Bearer internal-token" },
    "body": "{\"scope\": \"products\"}",
    "overlapPolicy": "SKIP"
  }'
python
import requests

resp = requests.post(
    "/api/cron-service/jobs",
    headers={"X-API-KEY": "your-api-key"},
    json={
        "name": "Refresh Cache",
        "cronExpression": "*/5 * * * *",
        "timezone": "UTC",
        "targetUrl": "https://api.mycompany.com/internal/cache/refresh",
        "httpMethod": "POST",
        "headers": {"Authorization": "Bearer internal-token"},
        "body": "{\"scope\": \"products\"}",
        "overlapPolicy": "SKIP"
    }
)
job = resp.json()["data"]
print(f"Job ID: {job['jobId']}, next run: {job['nextRunAt']}")
Response — 201 Created
{
  "status": "OK",
  "data": {
    "jobId": "job_8e4f2a1b",
    "name": "Refresh Cache",
    "cronExpression": "*/5 * * * *",
    "state": "ACTIVE",
    "nextRunAt": "2026-03-26T16:15:00Z",
    "overlapPolicy": "SKIP",
    "createdAt": "2026-03-26T16:12:30Z"
  }
}

Step 2: View Execution History

See the last runs for a job, including HTTP status codes and execution duration.

bash
curl -X GET "/api/cron-service/jobs/job_8e4f2a1b/executions?limit=5" \
  -H "X-API-KEY: your-api-key"
Response — 200 OK
{
  "status": "OK",
  "data": {
    "executions": [
      { "executionId": "ex_001", "startedAt": "2026-03-26T16:25:00Z", "durationMs": 230, "httpStatus": 200, "result": "SUCCESS" },
      { "executionId": "ex_002", "startedAt": "2026-03-26T16:20:00Z", "durationMs": 215, "httpStatus": 200, "result": "SUCCESS" },
      { "executionId": "ex_003", "startedAt": "2026-03-26T16:15:00Z", "durationMs": 8012, "httpStatus": 504, "result": "FAILED" }
    ]
  }
}

Step 3: Manual Run-Now

Trigger a job immediately without waiting for the next scheduled time. Useful for testing or on-demand cache busting.

bash
curl -X POST "/api/cron-service/jobs/job_8e4f2a1b/run" \
  -H "X-API-KEY: your-api-key"
Response — 202 Accepted
{
  "status": "OK",
  "data": {
    "executionId": "ex_004",
    "trigger": "MANUAL",
    "startedAt": "2026-03-26T16:27:45Z"
  }
}

Step 4: Overlap Policies

What happens when a scheduled run fires while the previous one is still executing?

Policy Behavior
SKIP Skip the new run if the previous is still in progress (default)
ALLOW Run in parallel — both executions proceed independently
CANCEL_PREVIOUS Abort the running execution and start the new one

Recommendation: Use SKIP for idempotent operations and CANCEL_PREVIOUS only when freshness matters more than completion.

Integration Tips

  • Cron syntax: Standard 5-field cron (min hour day month weekday). Use crontab.guru to build expressions.
  • Retry on failure: Set "retries": 3 and "retryDelaySeconds": 30 to auto-retry failed callbacks.
  • HMAC signatures: Enable "signPayloads": true and the service will sign each request with your API key so your endpoint can verify authenticity.
  • Pause/resume: PATCH the job state to PAUSED during maintenance windows.

Next Steps