Cron Jobs

Schedule HTTP requests to run automatically at specified intervals.

Overview

Cron jobs allow you to:

Schedule recurring HTTP requests to any URL
Monitor job execution status and history
Set custom headers and payloads
Configure timeouts and retry behavior
Trigger jobs manually for testing

Creating a Cron Job

Required Fields

Field	Description
`name`	Human-readable name for the job
`cronExpression`	Standard cron expression (5 fields)
`url`	The URL to call when the job runs

Optional Fields

Field	Description	Default
`description`	Optional description	-
`timezone`	Timezone for scheduling	`UTC`
`method`	HTTP method	`POST`
`headers`	Custom HTTP headers	-
`payload`	Request body (for POST/PUT/PATCH)	-
`timeoutMs`	Request timeout in milliseconds	`30000`

Cron Expression Format

Hookbase uses standard 5-field cron expressions:

┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-6, Sunday=0)
│ │ │ │ │
* * * * *

Special Characters

Character	Description	Example
`*`	Any value	`* * * * *` (every minute)
`*/n`	Every n units	`/5 * * *` (every 5 minutes)
`,`	List of values	`0,30 * * * *` (at 0 and 30 minutes)
`-`	Range of values	`0-5 * * * *` (minutes 0 through 5)

Common Patterns

Pattern	Description
`* * * * *`	Every minute
`/5 * * *`	Every 5 minutes
`/15 * * *`	Every 15 minutes
`0 * * * *`	Every hour (at minute 0)
`0 /2 * *`	Every 2 hours
`0 0 * * *`	Daily at midnight
`0 0 * * 0`	Weekly on Sunday at midnight
`0 0 1 * *`	Monthly on the 1st at midnight
`30 9 * * 1-5`	Weekdays at 9:30 AM

Examples

Daily Health Check

{
  "name": "Daily Health Check",
  "cronExpression": "0 9 * * *",
  "timezone": "America/New_York",
  "url": "https://api.example.com/health",
  "method": "GET",
  "timeoutMs": 10000
}

Hourly Data Sync

{
  "name": "Hourly Data Sync",
  "cronExpression": "0 * * * *",
  "url": "https://api.example.com/sync",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer your-api-key",
    "Content-Type": "application/json"
  },
  "payload": "{\"full_sync\": false}"
}

Weekly Report Generation

{
  "name": "Weekly Report",
  "cronExpression": "0 8 * * 1",
  "timezone": "Europe/London",
  "url": "https://api.example.com/reports/generate",
  "method": "POST",
  "headers": {
    "X-API-Key": "your-api-key"
  },
  "payload": "{\"report_type\": \"weekly_summary\"}",
  "timeoutMs": 60000
}

API Usage

Create Cron Job

curl -X POST https://api.hookbase.app/api/cron \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hourly Ping",
    "cronExpression": "0 * * * *",
    "url": "https://api.example.com/ping",
    "method": "GET"
  }'

Response:

{
  "cronJob": {
    "id": "cj_abc123",
    "name": "Hourly Ping",
    "cronExpression": "0 * * * *",
    "url": "https://api.example.com/ping",
    "nextRunAt": "2024-01-15 14:00:00"
  }
}

List Cron Jobs

curl https://api.hookbase.app/api/cron \
  -H "Authorization: Bearer whr_your_api_key"

Get Cron Job

curl https://api.hookbase.app/api/cron/{jobId} \
  -H "Authorization: Bearer whr_your_api_key"

Update Cron Job

curl -X PATCH https://api.hookbase.app/api/cron/{jobId} \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "cronExpression": "*/30 * * * *",
    "isActive": true
  }'

Delete Cron Job

curl -X DELETE https://api.hookbase.app/api/cron/{jobId} \
  -H "Authorization: Bearer whr_your_api_key"

Trigger Job Manually

Run a job immediately, regardless of its schedule:

curl -X POST https://api.hookbase.app/api/cron/{jobId}/trigger \
  -H "Authorization: Bearer whr_your_api_key"

Response:

{
  "execution": {
    "id": "exec_xyz789",
    "status": "success",
    "responseStatus": 200,
    "latencyMs": 245
  }
}

Get Execution History

curl https://api.hookbase.app/api/cron/{jobId}/executions?limit=20 \
  -H "Authorization: Bearer whr_your_api_key"

Response:

{
  "executions": [
    {
      "id": "exec_xyz789",
      "status": "success",
      "responseStatus": 200,
      "latencyMs": 245,
      "startedAt": "2024-01-15T13:00:00Z",
      "completedAt": "2024-01-15T13:00:00Z"
    },
    {
      "id": "exec_abc456",
      "status": "failed",
      "errorMessage": "Connection timeout",
      "latencyMs": 30000,
      "startedAt": "2024-01-15T12:00:00Z",
      "completedAt": "2024-01-15T12:00:30Z"
    }
  ]
}

Execution Status

Status	Description
`running`	Job is currently executing
`success`	Job completed with 2xx response
`failed`	Job failed (timeout, error, or non-2xx response)

Best Practices

Use appropriate timeouts: Set timeoutMs based on expected response time. Default is 30 seconds.
Monitor executions: Regularly check execution history for failures.
Start with longer intervals: Begin with less frequent schedules and adjust as needed.
Use descriptive names: Make job names clear and searchable.
Test with manual trigger: Use the trigger endpoint to test before enabling scheduled runs.
Consider timezone: Set the appropriate timezone for business-hour schedules.

Limitations

Minimum interval: 1 minute (* * * * *)
Maximum timeout: 60 seconds
Jobs are checked every minute by the scheduler
Response bodies are truncated to 10KB in execution logs

Use Cases

Heartbeat Monitoring

Keep external services aware that your system is running:

{
  "name": "Heartbeat",
  "cronExpression": "*/5 * * * *",
  "url": "https://monitoring.example.com/heartbeat",
  "method": "POST",
  "payload": "{\"service\": \"webhook-relay\"}"
}

Cache Warming

Pre-populate caches before peak hours:

{
  "name": "Cache Warm",
  "cronExpression": "0 7 * * *",
  "url": "https://api.example.com/cache/warm",
  "method": "POST"
}

Database Cleanup

Schedule regular maintenance tasks:

{
  "name": "Cleanup Old Records",
  "cronExpression": "0 3 * * *",
  "url": "https://api.example.com/cleanup",
  "method": "POST",
  "payload": "{\"older_than_days\": 30}"
}

Slack Notifications

Send scheduled team notifications:

{
  "name": "Daily Standup Reminder",
  "cronExpression": "55 8 * * 1-5",
  "timezone": "America/New_York",
  "url": "https://hooks.slack.com/services/xxx/yyy/zzz",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json"
  },
  "payload": "{\"text\": \"Standup in 5 minutes!\"}"
}

Cron Jobs

Schedule HTTP requests to run automatically at specified intervals.

Overview

Cron jobs allow you to:

Schedule recurring HTTP requests to any URL
Monitor job execution status and history
Set custom headers and payloads
Configure timeouts and retry behavior
Trigger jobs manually for testing

Creating a Cron Job

Required Fields

Field	Description
`name`	Human-readable name for the job
`cronExpression`	Standard cron expression (5 fields)
`url`	The URL to call when the job runs

Optional Fields

Field	Description	Default
`description`	Optional description	-
`timezone`	Timezone for scheduling	`UTC`
`method`	HTTP method	`POST`
`headers`	Custom HTTP headers	-
`payload`	Request body (for POST/PUT/PATCH)	-
`timeoutMs`	Request timeout in milliseconds	`30000`

Cron Expression Format

Hookbase uses standard 5-field cron expressions:

┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-6, Sunday=0)
│ │ │ │ │
* * * * *

Special Characters

Character	Description	Example
`*`	Any value	`* * * * *` (every minute)
`*/n`	Every n units	`/5 * * *` (every 5 minutes)
`,`	List of values	`0,30 * * * *` (at 0 and 30 minutes)
`-`	Range of values	`0-5 * * * *` (minutes 0 through 5)

Common Patterns

Pattern	Description
`* * * * *`	Every minute
`/5 * * *`	Every 5 minutes
`/15 * * *`	Every 15 minutes
`0 * * * *`	Every hour (at minute 0)
`0 /2 * *`	Every 2 hours
`0 0 * * *`	Daily at midnight
`0 0 * * 0`	Weekly on Sunday at midnight
`0 0 1 * *`	Monthly on the 1st at midnight
`30 9 * * 1-5`	Weekdays at 9:30 AM

Examples

Daily Health Check

{
  "name": "Daily Health Check",
  "cronExpression": "0 9 * * *",
  "timezone": "America/New_York",
  "url": "https://api.example.com/health",
  "method": "GET",
  "timeoutMs": 10000
}

Hourly Data Sync

{
  "name": "Hourly Data Sync",
  "cronExpression": "0 * * * *",
  "url": "https://api.example.com/sync",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer your-api-key",
    "Content-Type": "application/json"
  },
  "payload": "{\"full_sync\": false}"
}

Weekly Report Generation

{
  "name": "Weekly Report",
  "cronExpression": "0 8 * * 1",
  "timezone": "Europe/London",
  "url": "https://api.example.com/reports/generate",
  "method": "POST",
  "headers": {
    "X-API-Key": "your-api-key"
  },
  "payload": "{\"report_type\": \"weekly_summary\"}",
  "timeoutMs": 60000
}

API Usage

Create Cron Job

curl -X POST https://api.hookbase.app/api/cron \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hourly Ping",
    "cronExpression": "0 * * * *",
    "url": "https://api.example.com/ping",
    "method": "GET"
  }'

Response:

{
  "cronJob": {
    "id": "cj_abc123",
    "name": "Hourly Ping",
    "cronExpression": "0 * * * *",
    "url": "https://api.example.com/ping",
    "nextRunAt": "2024-01-15 14:00:00"
  }
}

List Cron Jobs

curl https://api.hookbase.app/api/cron \
  -H "Authorization: Bearer whr_your_api_key"

Get Cron Job

curl https://api.hookbase.app/api/cron/{jobId} \
  -H "Authorization: Bearer whr_your_api_key"

Update Cron Job

curl -X PATCH https://api.hookbase.app/api/cron/{jobId} \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "cronExpression": "*/30 * * * *",
    "isActive": true
  }'

Delete Cron Job

curl -X DELETE https://api.hookbase.app/api/cron/{jobId} \
  -H "Authorization: Bearer whr_your_api_key"

Trigger Job Manually

Run a job immediately, regardless of its schedule:

curl -X POST https://api.hookbase.app/api/cron/{jobId}/trigger \
  -H "Authorization: Bearer whr_your_api_key"

Response:

{
  "execution": {
    "id": "exec_xyz789",
    "status": "success",
    "responseStatus": 200,
    "latencyMs": 245
  }
}

Get Execution History

curl https://api.hookbase.app/api/cron/{jobId}/executions?limit=20 \
  -H "Authorization: Bearer whr_your_api_key"

Response:

{
  "executions": [
    {
      "id": "exec_xyz789",
      "status": "success",
      "responseStatus": 200,
      "latencyMs": 245,
      "startedAt": "2024-01-15T13:00:00Z",
      "completedAt": "2024-01-15T13:00:00Z"
    },
    {
      "id": "exec_abc456",
      "status": "failed",
      "errorMessage": "Connection timeout",
      "latencyMs": 30000,
      "startedAt": "2024-01-15T12:00:00Z",
      "completedAt": "2024-01-15T12:00:30Z"
    }
  ]
}

Execution Status

Status	Description
`running`	Job is currently executing
`success`	Job completed with 2xx response
`failed`	Job failed (timeout, error, or non-2xx response)

Best Practices

Use appropriate timeouts: Set timeoutMs based on expected response time. Default is 30 seconds.
Monitor executions: Regularly check execution history for failures.
Start with longer intervals: Begin with less frequent schedules and adjust as needed.
Use descriptive names: Make job names clear and searchable.
Test with manual trigger: Use the trigger endpoint to test before enabling scheduled runs.
Consider timezone: Set the appropriate timezone for business-hour schedules.

Limitations

Minimum interval: 1 minute (* * * * *)
Maximum timeout: 60 seconds
Jobs are checked every minute by the scheduler
Response bodies are truncated to 10KB in execution logs

Use Cases

Heartbeat Monitoring

Keep external services aware that your system is running:

{
  "name": "Heartbeat",
  "cronExpression": "*/5 * * * *",
  "url": "https://monitoring.example.com/heartbeat",
  "method": "POST",
  "payload": "{\"service\": \"webhook-relay\"}"
}

Cache Warming

Pre-populate caches before peak hours:

{
  "name": "Cache Warm",
  "cronExpression": "0 7 * * *",
  "url": "https://api.example.com/cache/warm",
  "method": "POST"
}

Database Cleanup

Schedule regular maintenance tasks:

{
  "name": "Cleanup Old Records",
  "cronExpression": "0 3 * * *",
  "url": "https://api.example.com/cleanup",
  "method": "POST",
  "payload": "{\"older_than_days\": 30}"
}

Slack Notifications

Send scheduled team notifications:

{
  "name": "Daily Standup Reminder",
  "cronExpression": "55 8 * * 1-5",
  "timezone": "America/New_York",
  "url": "https://hooks.slack.com/services/xxx/yyy/zzz",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json"
  },
  "payload": "{\"text\": \"Standup in 5 minutes!\"}"
}