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

WebhookRelay 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

json

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

Hourly Data Sync

json

{
  "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

json

{
  "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

bash

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

Response:

json

{
  "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

bash

curl https://api.hookbase.app/api/organizations/{orgId}/cron \
  -H "Authorization: Bearer YOUR_TOKEN"

Get Cron Job

bash

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

Update Cron Job

bash

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

Delete Cron Job

bash

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

Trigger Job Manually

Run a job immediately, regardless of its schedule:

bash

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

Response:

json

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

Get Execution History

bash

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

Response:

json

{
  "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:

json

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

Cache Warming

Pre-populate caches before peak hours:

json

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

Database Cleanup

Schedule regular maintenance tasks:

json

{
  "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:

json

{
  "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 ​

Overview ​

Creating a Cron Job ​

Required Fields ​

Optional Fields ​

Cron Expression Format ​

Special Characters ​

Common Patterns ​

Examples ​

Daily Health Check ​

Hourly Data Sync ​

Weekly Report Generation ​

API Usage ​

Create Cron Job ​

List Cron Jobs ​

Get Cron Job ​

Update Cron Job ​

Delete Cron Job ​

Trigger Job Manually ​

Get Execution History ​

Execution Status ​

Best Practices ​

Limitations ​

Use Cases ​

Heartbeat Monitoring ​

Cache Warming ​

Database Cleanup ​

Slack Notifications ​

Cron Jobs

Overview

Creating a Cron Job

Required Fields

Optional Fields

Cron Expression Format

Special Characters

Common Patterns

Examples

Daily Health Check

Hourly Data Sync

Weekly Report Generation

API Usage

Create Cron Job

List Cron Jobs

Get Cron Job

Update Cron Job

Delete Cron Job

Trigger Job Manually

Get Execution History

Execution Status

Best Practices

Limitations

Use Cases

Heartbeat Monitoring

Cache Warming

Database Cleanup

Slack Notifications