API Reference

Everything you need to schedule webhook calls with CronHook.

Overview

CronHook is a REST API for scheduling recurring HTTP webhook calls. You define a cron expression and a target URL — CronHook fires a POST request to that URL on your schedule.

There is no dashboard. Everything is done via API.

Base URL

https://api.cronhook.io

Authentication

All endpoints (except /register) require a bearer token.

HTTP header
Authorization: Bearer cron_your_api_key

Your API key is returned once at registration. It cannot be retrieved again — use key rotation if you lose it.

Errors

All errors return standard HTTP status codes with a JSON body:

{"detail": "Invalid cron expression"}

Status	Meaning
400	Bad request — invalid input
401	Missing or invalid API key
403	Plan limit reached
404	Resource not found
422	Validation error
429	Rate limit exceeded

Rate limits

Rate limits are enforced per IP address.

Endpoint	Limit
/register	10 / hour
/jobs (all)	60 / minute
/request-key-rotation	5 / hour
/rotate-key	10 / hour

Register

POST /register

Create an account and receive an API key. The key is only shown once — store it securely.

Request body

Field	Type	Description
email required	string	Your email address. Used for key rotation only.

Example

Request

          curl -X POST https://api.cronhook.io/register -H "Content-Type: application/json" -d '{"email":"you@example.com"}'

Response · 201

{
  "api_key": "cron_abc123...",
  "note": "Store this key — it will not be shown again"
}

Key rotation

If you lose your API key, request a rotation token by email. The token is single-use and expires in 15 minutes.

Step 1 — Request a rotation token

POST /request-key-rotation

Request

          curl -X POST https://api.cronhook.io/request-key-rotation -H "Content-Type: application/json" -d '{"email":"you@example.com"}'

Step 2 — Exchange token for new key

POST /rotate-key

Request

          curl -X POST https://api.cronhook.io/rotate-key -H "Content-Type: application/json" -d '{"token":"token-from-email"}'

Create job

POST /jobs

Create a new scheduled job. CronHook will POST to your webhook_url on the schedule defined by cron_expression.

Request body

Field	Type	Description
name required	string	A label for the job. Max 100 characters.
cron_expression required	string	Standard 5-field cron expression. E.g. `0 * * * *` (every hour).
webhook_url required	string	The URL to POST to. Must be publicly reachable (https recommended). Max 2048 chars.
headers	object	Optional HTTP headers to include. Max 20 headers, keys ≤100 chars, values ≤500 chars.
payload	object	Optional JSON body to POST. Max 10KB.

Cron expression reference

Expression	Schedule
* * * * *	Every minute
0 * * * *	Every hour
0 9 * * *	Daily at 09:00 UTC
0 9 * * 1	Every Monday at 09:00 UTC
0 0 1 * *	First day of every month
/15 * * *	Every 15 minutes

All times are UTC.

Example

Request

          curl -X POST https://api.cronhook.io/jobs -H "Authorization: Bearer cron_abc123..." -H "Content-Type: application/json" -d '{"name":"hourly-sync","cron_expression":"0 * * * *","webhook_url":"https://your-app.com/sync","headers":{"X-Secret":"mytoken"}}'

Response · 201

{
  "id": 1,
  "name": "hourly-sync",
  "cron_expression": "0 * * * *",
  "webhook_url": "https://your-app.com/sync",
  "headers": {"X-Secret": "mytoken"},
  "payload": null,
  "enabled": true,
  "next_run_at": "2026-05-09T14:00:00+00:00",
  "created_at": "2026-05-09T13:22:10+00:00"
}

List jobs

GET /jobs

Returns all jobs for your account, ordered by creation date descending.

Request

          curl https://api.cronhook.io/jobs -H "Authorization: Bearer cron_abc123..."

Update job

PATCH /jobs/{id}

Update any fields on a job. All fields are optional — only send what you want to change.

Request body

Field	Type	Description
name	string	New job name.
cron_expression	string	New cron schedule. Recalculates next_run_at immediately.
webhook_url	string	New webhook target URL.
headers	object	Replace all headers.
payload	object	Replace the payload body.
enabled	boolean	Pause (`false`) or resume (`true`) the job.

Example — pause a job

Request

          curl -X PATCH https://api.cronhook.io/jobs/1 -H "Authorization: Bearer cron_abc123..." -H "Content-Type: application/json" -d '{"enabled":false}'

Delete job

DELETE /jobs/{id}

Permanently delete a job and stop all future executions. Returns 204 No Content on success.

Request

          curl -X DELETE https://api.cronhook.io/jobs/1 -H "Authorization: Bearer cron_abc123..."

List executions

GET /jobs/{id}/executions

Returns the last 100 executions for a job, most recent first. Use this to check if your webhook is being called and whether it's succeeding.

Request

          curl https://api.cronhook.io/jobs/1/executions -H "Authorization: Bearer cron_abc123..."

Response · 200

[
  {
    "id": 42,
    "job_id": 1,
    "status": "success",
    "response_code": 200,
    "duration_ms": 312,
    "error": null,
    "completed_at": "2026-05-09T13:00:00+00:00"
  },
  {
    "id": 41,
    "job_id": 1,
    "status": "failure",
    "response_code": 503,
    "duration_ms": 1043,
    "error": "HTTP 503",
    "completed_at": "2026-05-09T12:00:00+00:00"
  }
]

Execution status values

Status	Meaning
pending	Queued, not yet fired
success	Webhook responded with 2xx or 3xx
failure	Webhook responded 4xx/5xx, timed out, or URL was blocked

Need help?

Email hello@cronhook.io — we respond within 24 hours.