Quick Start: Push (HTTP)

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

Prerequisites

• Node.js 20 or later
• A Chronos account (sign up free)
• An API key (create one in the dashboard under Settings → API Keys)
• A publicly reachable HTTPS endpoint (or a tunnel for local dev)

Tip

For local development, use a tunnel like ngrok: ngrok http 3000. Use the generated HTTPS URL as your push endpoint.

1. Install Express

   pnpm

   pnpm add express

   npm

   npm install express

   yarn

   yarn 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

   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:

   curl -X POST https://api.chronos.sh/v1/jobs \
     -H "Authorization: Bearer chrns_your_api_key" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "My first job",
       "handler": "hello",
       "delivery": {
         "type": "push",
         "http": {
           "url": "https://your-server.com/hooks/chronos",
           "method": "POST"
         }
       }
     }'

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

   Job a8f3e2b1-... running (attempt 1)

What just happened

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.

Make it recurring

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

curl -X POST https://api.chronos.sh/v1/schedules \
  -H "Authorization: Bearer chrns_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hello every 10 minutes",
    "handler": "hello",
    "interval": { "value": 10, "unit": "minute" },
    "delivery": {
      "type": "push",
      "http": {
        "url": "https://your-server.com/hooks/chronos",
        "method": "POST"
      }
    }
  }'

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

curl -X POST https://api.chronos.sh/v1/schedules/SCHEDULE_ID/archive \
  -H "Authorization: Bearer chrns_your_api_key"

Note

The free tier supports intervals of 10 minutes or longer. See Pricing & Limits for all plan limits.

Next steps

Signature Verification Verify that requests actually come from Chronos

Push Delivery Response rules, custom headers, debugging tips

API Reference Full endpoint documentation