Cron Jobs API
Schedule recurring HTTP requests to run automatically.
Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /api/cron | List cron jobs |
| POST | /api/cron | Create cron job |
| GET | /api/cron/{id} | Get cron job |
| PATCH | /api/cron/{id} | Update cron job |
| DELETE | /api/cron/{id} | Delete cron job |
| POST | /api/cron/{id}/trigger | Trigger job manually |
| GET | /api/cron/{id}/executions | Get execution history |
Cron Job Object
{
"id": "cj_abc123",
"name": "Hourly Sync",
"description": "Sync data every hour",
"cronExpression": "0 * * * *",
"timezone": "UTC",
"url": "https://api.example.com/sync",
"method": "POST",
"headers": {
"Authorization": "Bearer xxx",
"Content-Type": "application/json"
},
"payload": "{\"full\": false}",
"timeoutMs": 30000,
"isActive": true,
"lastRunAt": "2024-01-15T10:00:00Z",
"nextRunAt": "2024-01-15T11:00:00Z",
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-15T10:00:00Z"
}Execution Object
{
"id": "exec_xyz789",
"cronJobId": "cj_abc123",
"status": "success",
"responseStatus": 200,
"responseBody": "{\"ok\": true}",
"errorMessage": null,
"latencyMs": 245,
"startedAt": "2024-01-15T10:00:00Z",
"completedAt": "2024-01-15T10:00:00Z"
}List Cron Jobs
GET /api/cronExample
curl https://api.hookbase.app/api/organizations/org_123/cron \
-H "Authorization: Bearer whr_your_api_key"Response
{
"cronJobs": [
{
"id": "cj_abc123",
"name": "Hourly Sync",
"cronExpression": "0 * * * *",
"url": "https://api.example.com/sync",
"method": "POST",
"isActive": true,
"lastRunAt": "2024-01-15T10:00:00Z",
"nextRunAt": "2024-01-15T11:00:00Z"
}
]
}Create Cron Job
POST /api/cronRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Display name |
| cronExpression | string | Yes | 5-field cron expression |
| url | string | Yes | Target URL to call |
| description | string | No | Optional description |
| timezone | string | No | Timezone (default: UTC) |
| method | string | No | HTTP method (default: POST) |
| headers | object | No | Custom HTTP headers |
| payload | string | No | Request body |
| timeoutMs | number | No | Timeout in ms (default: 30000) |
Cron Expression Format
Standard 5-field cron expression: minute hour day month weekday
| Field | Range | Special Characters |
|---|---|---|
| Minute | 0-59 | *, */n, ,, - |
| Hour | 0-23 | *, */n, ,, - |
| Day of Month | 1-31 | *, */n, ,, - |
| Month | 1-12 | *, */n, ,, - |
| Day of Week | 0-6 | *, */n, ,, - |
Example
curl -X POST https://api.hookbase.app/api/organizations/org_123/cron \
-H "Authorization: Bearer whr_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"name": "Daily Cleanup",
"cronExpression": "0 3 * * *",
"timezone": "America/New_York",
"url": "https://api.example.com/cleanup",
"method": "POST",
"headers": {
"Authorization": "Bearer api-key-here"
},
"payload": "{\"older_than_days\": 30}",
"timeoutMs": 60000
}'Response
{
"cronJob": {
"id": "cj_def456",
"name": "Daily Cleanup",
"cronExpression": "0 3 * * *",
"url": "https://api.example.com/cleanup",
"nextRunAt": "2024-01-16 03:00:00"
}
}Get Cron Job
GET /api/cron/{id}Example
curl https://api.hookbase.app/api/organizations/org_123/cron/cj_abc123 \
-H "Authorization: Bearer whr_your_api_key"Response
{
"cronJob": {
"id": "cj_abc123",
"name": "Hourly Sync",
"description": "Sync data every hour",
"cronExpression": "0 * * * *",
"timezone": "UTC",
"url": "https://api.example.com/sync",
"method": "POST",
"headers": "{\"Authorization\":\"Bearer xxx\"}",
"payload": "{\"full\": false}",
"timeoutMs": 30000,
"isActive": true,
"lastRunAt": "2024-01-15T10:00:00Z",
"nextRunAt": "2024-01-15T11:00:00Z",
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-15T10:00:00Z"
}
}Update Cron Job
PATCH /api/cron/{id}Request Body
All fields are optional. Only provided fields are updated.
| Field | Type | Description |
|---|---|---|
| name | string | Display name |
| description | string | Optional description |
| cronExpression | string | 5-field cron expression |
| timezone | string | Timezone |
| url | string | Target URL |
| method | string | HTTP method |
| headers | object | Custom HTTP headers |
| payload | string | Request body |
| timeoutMs | number | Timeout in milliseconds |
| isActive | boolean | Enable/disable the job |
Example
curl -X PATCH https://api.hookbase.app/api/organizations/org_123/cron/cj_abc123 \
-H "Authorization: Bearer whr_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"cronExpression": "*/30 * * * *",
"isActive": false
}'Response
{
"success": true
}Delete Cron Job
DELETE /api/cron/{id}Warning
Deleting a cron job also deletes all its execution history.
Example
curl -X DELETE https://api.hookbase.app/api/organizations/org_123/cron/cj_abc123 \
-H "Authorization: Bearer whr_your_api_key"Response
{
"success": true
}Trigger Job Manually
Execute a cron job immediately, regardless of its schedule.
POST /api/cron/{id}/triggerExample
curl -X POST https://api.hookbase.app/api/organizations/org_123/cron/cj_abc123/trigger \
-H "Authorization: Bearer whr_your_api_key"Response (Success)
{
"execution": {
"id": "exec_xyz789",
"status": "success",
"responseStatus": 200,
"latencyMs": 245
}
}Response (Failure)
{
"execution": {
"id": "exec_abc456",
"status": "failed",
"error": "Connection timeout",
"latencyMs": 30000
}
}Get Execution History
GET /api/cron/{id}/executionsQuery Parameters
| Parameter | Type | Description |
|---|---|---|
| limit | number | Number of executions to return (default: 20) |
Example
curl "https://api.hookbase.app/api/organizations/org_123/cron/cj_abc123/executions?limit=10" \
-H "Authorization: Bearer whr_your_api_key"Response
{
"executions": [
{
"id": "exec_xyz789",
"cron_job_id": "cj_abc123",
"status": "success",
"response_status": 200,
"response_body": "{\"ok\": true}",
"error_message": null,
"latency_ms": 245,
"started_at": "2024-01-15T10:00:00Z",
"completed_at": "2024-01-15T10:00:00Z"
},
{
"id": "exec_abc456",
"cron_job_id": "cj_abc123",
"status": "failed",
"response_status": null,
"response_body": null,
"error_message": "Connection timeout",
"latency_ms": 30000,
"started_at": "2024-01-15T09:00:00Z",
"completed_at": "2024-01-15T09:00:30Z"
}
]
}Execution Status Values
| Status | Description |
|---|---|
running | Job is currently executing |
success | Completed with HTTP 2xx response |
failed | Failed due to error, timeout, or non-2xx response |
Error Responses
400 Bad Request
Invalid cron expression:
{
"error": "Invalid cron expression"
}Invalid URL:
{
"error": "Invalid URL"
}Missing required fields:
{
"error": "Name, cron expression, and URL are required"
}404 Not Found
Cron job not found:
{
"error": "Cron job not found"
}Rate Limits
- Jobs execute no more frequently than once per minute
- Maximum timeout per execution: 60 seconds
- Response body stored in execution logs: 10KB max