Skip to content

Quick Start: Push (HTTP)

Chronos sends HTTP requests to your endpoint when a job is due. No long-lived worker process needed.

  • Node.js 20 or later
  • A Chronos account (sign up free)
  • An API key (create one in the dashboard under Settings → Keys with the Full access or CI and deploys preset)
  • A publicly reachable HTTPS endpoint (or a tunnel for local dev)
  • For the Node.js tabs, @chronos.sh/sdk 0.2.0 or later, installed with the package manager from step 1
  • For the Go tabs, Go 1.26 or later
  • For the CLI tabs, the chronos CLI
  1. Install Express

    Terminal window
    pnpm add express
  2. Write your handler

    server.mjs
    import express from 'express';
    const app = express();
    app.use(express.json());
    app.post('/hooks/chronos', (req, res) => {
    const { handler, payload, job_id, attempt } = req.body;
    if (handler !== 'hello') {
    console.warn(`Unknown handler: ${handler}`);
    return res.sendStatus(400);
    }
    console.log(`Job ${job_id} running (attempt ${attempt})`);
    res.sendStatus(200);
    });
    app.listen(3000, () => console.log('Listening on :3000'));

    Return 200 for success, 4xx for permanent failures, 5xx for transient failures you want retried.

  3. Start the server

    Terminal window
    node server.mjs

    Your server is now listening on port 3000.

  4. Create a job

    In a second terminal, create a one-off job with push delivery:

    Terminal window
    CHRONOS_API_KEY=chrns_your_api_key chronos jobs create --name 'My first job' --handler hello \
    --push-url https://your-server.com/hooks/chronos

    Chronos sends an HTTP request to your endpoint. You should see:

    Job a8f3e2b1-... running (attempt 1)
  1. You created a one-off job with push delivery
  2. Chronos sent an HTTP POST to your endpoint
  3. Your handler processed the request and returned 200
  4. Chronos recorded the execution as completed

If your endpoint had returned 5xx or timed out, Chronos would have retried up to 3 times with exponential backoff.

Create a schedule with push delivery and your server receives jobs automatically:

Terminal window
CHRONOS_API_KEY=chrns_your_api_key chronos schedules create --name 'Hello every 10 minutes' --handler hello --interval 10m \
--push-url https://your-server.com/hooks/chronos

The command prints the schedule, including its id.

Your running server now receives a new request every 10 minutes. To stop it, archive the schedule:

Terminal window
CHRONOS_API_KEY=chrns_your_api_key chronos schedules archive SCHEDULE_ID