Push Delivery
When to use push delivery
Section titled “When to use push delivery”Use push if you already have a server listening or want jobs delivered to serverless functions. No long-lived worker process needed. Chronos makes the HTTP request to you.
If you’d rather pull jobs from your own process, see Worker Setup for Node.js or the Go SDK pull worker.
Create a schedule with push delivery
Section titled “Create a schedule with push delivery”chronos schedules create --name 'Daily report' --handler generate-report --cron '0 9 * * *' \ --push-url https://your-app.com/hooks/chronos --payload '{"format":"pdf"}'curl -X POST https://api.chronos.sh/v1/schedules \ -H "Authorization: Bearer chrns_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "name": "Daily report", "handler": "generate-report", "cron": "0 9 * * *", "delivery": { "type": "push", "http": { "url": "https://your-app.com/hooks/chronos", "method": "POST" } }, "payload": { "format": "pdf" } }'import { Chronos } from '@chronos.sh/sdk';
const chronos = new Chronos({ apiKey: process.env.CHRONOS_API_KEY! });
await chronos.schedules.create({ name: 'Daily report', handler: 'generate-report', cron: '0 9 * * *', delivery: { type: 'push', http: { url: 'https://your-app.com/hooks/chronos', method: 'POST' }, }, payload: { format: 'pdf' },});client, err := chronos.NewClient(os.Getenv("CHRONOS_API_KEY"))if err != nil { return err}_, err = client.Schedules.Create(context.Background(), chronos.ScheduleCreateParams{ Name: "Daily report", Handler: new("generate-report"), Cron: new("0 9 * * *"), Delivery: &chronos.Delivery{ Type: chronos.DeliveryTypePush, HTTP: &chronos.HTTPDelivery{URL: "https://your-app.com/hooks/chronos", Method: "POST"}, }, Payload: map[string]any{"format": "pdf"},})if err != nil { return err}The delivery.http object supports:
| Field | Type | Required | Description |
|---|---|---|---|
url |
string |
Yes | Your endpoint. Must be HTTPS in production. No private/localhost IPs. |
method |
string |
Yes | GET, POST, PUT, PATCH, or DELETE |
headers |
Record<string, string> |
No | Custom headers sent with every delivery |
Custom headers example:
"http": { "url": "https://your-app.com/hooks/chronos", "method": "POST", "headers": { "X-App-Secret": "your-shared-secret" }}What Chronos sends
Section titled “What Chronos sends”When a job is due, Chronos makes an HTTP request to your endpoint.
Request body
Section titled “Request body”{ "type": "job", "job_id": "a1b2c3d4-...", "handler": "generate-report", "execution_id": "e5f6g7h8-...", "scheduled_for": "2026-01-15T09:00:00.000Z", "attempt": 1, "payload": { "format": "pdf" }}| Field | Type | Description |
|---|---|---|
type |
string |
"job" for a job delivery, "test" for a test request from the dashboard. Covered by the signature. |
job_id |
string |
Stable job identifier. Same across retries. |
handler |
string | null |
The handler name from your schedule. null if not set. |
execution_id |
string |
Unique to this attempt. Use job_id for idempotency across retries. |
scheduled_for |
string |
ISO 8601 timestamp of when the job was scheduled. |
attempt |
number |
Attempt number. 1 on first try, increments on retries. |
payload |
object | null |
The payload from your schedule or job. |
Headers
Section titled “Headers”Every delivery includes these system headers:
| Header | Value | Description |
|---|---|---|
Content-Type |
application/json |
Always JSON |
User-Agent |
chronos.sh/1.0 |
Identifies Chronos |
X-Chronos-Signature |
sha256=<hex> |
HMAC-SHA256 signature for verification |
X-Chronos-Delivery-Id |
<delivery_id> |
The id the signature covers. Equals execution_id on a job delivery. |
X-Chronos-Timestamp |
<unix_seconds> |
Request timestamp (seconds since epoch) |
X-Chronos-Event |
job |
job for a job delivery, test for a test request. The signature doesn’t cover it, so check the body’s type instead. |
Your custom headers (from delivery.http.headers) are included, except headers named Content-Type, User-Agent, Host, X-Chronos-*, or connection-level headers, which Chronos drops. Credentials in the URL (https://user:pass@host/...) are sent as an Authorization: Basic header, which replaces a custom Authorization header.
Chronos does not follow redirects.
Handle the delivery
Section titled “Handle the delivery”A minimal Express handler:
import express from 'express';
const app = express();app.use(express.json());
app.post('/hooks/chronos', async (req, res) => { const { type, handler, payload } = req.body;
if (type === 'test') { return res.sendStatus(200); }
switch (handler) { case 'generate-report': await generateReport(payload.format); break; case 'sync-tenant': await syncTenant(payload.tenantId); break; default: console.warn(`Unknown handler: ${handler}`); return res.sendStatus(400); }
res.sendStatus(200);});
app.listen(3000);Route by the handler field to dispatch different job types to a single endpoint. The dashboard’s Test button sends a body with "type": "test" and no handler, so answer it with a 2xx. Returning 400 for unknown handlers prevents Chronos from recording work as completed when nothing ran. For handlers you expect to deploy soon, return 503 instead so Chronos retries.
Response rules
Section titled “Response rules”Your HTTP response tells Chronos what happened:
| Your response | Chronos records | Retries? |
|---|---|---|
| 2xx (any success) | completed |
No |
| 4xx (client error) | failed |
No: terminal |
| 5xx (server error) | failed |
Yes: exponential backoff |
| Timeout (no response within limit) | timeout |
Yes |
| Network error (connection refused, DNS failure) | failed |
Yes |
Verify the signature
Section titled “Verify the signature”Every delivery is signed with your workspace’s signing secret (found in the dashboard under Settings → Keys). Verify the X-Chronos-Signature header to confirm requests come from Chronos and haven’t been tampered with.
The SDK provides a Webhook class that handles verification:
import { Webhook, ChronosWebhookVerificationError } from '@chronos.sh/sdk';
const wh = new Webhook(process.env.CHRONOS_SIGNING_SECRET!);
// In your request handler (rawBody = the exact bytes received):try { const payload = await wh.verify(rawBody, req.headers);} catch (err) { if (err instanceof ChronosWebhookVerificationError) { return res.sendStatus(401); }}See Signature Verification for how to capture the raw body in Express, key rotation, and replay protection options.
One-off jobs with push delivery
Section titled “One-off jobs with push delivery”The same delivery config works on one-off jobs:
chronos jobs create --name 'Send welcome email' --handler send-email --delay 30m \ --push-url https://your-app.com/hooks/chronos --payload '{"userId":"usr_abc123","template":"welcome"}'curl -X POST https://api.chronos.sh/v1/jobs \ -H "Authorization: Bearer chrns_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "name": "Send welcome email", "handler": "send-email", "delay": { "value": 30, "unit": "minute" }, "delivery": { "type": "push", "http": { "url": "https://your-app.com/hooks/chronos", "method": "POST" } }, "payload": { "userId": "usr_abc123", "template": "welcome" } }'await chronos.jobs.create({ name: 'Send welcome email', handler: 'send-email', delay: { value: 30, unit: 'minute' }, delivery: { type: 'push', http: { url: 'https://your-app.com/hooks/chronos', method: 'POST' }, }, payload: { userId: 'usr_abc123', template: 'welcome' },});_, err = client.Jobs.Create(context.Background(), chronos.JobCreateParams{ Name: "Send welcome email", Handler: new("send-email"), Delay: &chronos.Interval{Value: 30, Unit: chronos.IntervalUnitMinute}, Delivery: &chronos.Delivery{ Type: chronos.DeliveryTypePush, HTTP: &chronos.HTTPDelivery{URL: "https://your-app.com/hooks/chronos", Method: "POST"}, }, Payload: map[string]any{"userId": "usr_abc123", "template": "welcome"},})if err != nil { return err}Debugging tips
Section titled “Debugging tips”- Check your response time. Default timeout is 30 seconds. If your handler takes longer, increase
timeouton the schedule/job (up to your plan’s cap) or optimize the handler. - 4xx is terminal. If you accidentally return 401/403 (e.g., middleware rejecting the request), Chronos won’t retry. Return 503 while you fix auth issues.
- Correlate with
X-Chronos-Delivery-Id. This matchesexecution_id. Use it to find the delivery in your logs and in the Chronos dashboard. attempttells you which retry you’re on. Use it to adjust behavior on later attempts (e.g., skip optional steps, use a simpler fallback).