Tasks
Tasks are the core asynchronous operations in Taskhook. This guide covers the endpoints you can use to create, monitor, and manage tasks programmatically.
The task model
The task model contains all the information about your asynchronous tasks, including their current status, execution attempts, and associated target callback URLs.
Submit a task
This endpoint allows you to submit a new task for asynchronous processing. You can specify the target endpoint or group, notification preferences, and execution timing.
Required attributes
- Name
target- Type
- string | object
- Description
The target endpoint or group. Can be:
- URL string: "https://api.example.com/process"
- Group reference: "group:invoice-processors"
- Configuration object:
{ "url": "https://api.example.com/process", "method": "POST", "headers": {"X-Custom": "value"} }
Optional attributes
- Name
notifications- Type
- string | object | array
- Description
Configuration for status notifications. Can be:
- URL string: "https://api.example.com/status"
- Configuration object:
{ "url": "https://api.example.com/status", "method": "POST", "headers": {"X-Custom": "value"}, "events": ["task.completed", "group.first_failed"] } - Array of configuration objects for multiple notification endpoints
Read about notification events for more details.
- Name
execute_after- Type
- string
- Description
ISO8601 timestamp for earliest execution time or ISO8601 duration string.
- Name
expires_after- Type
- string
- Description
ISO8601 timestamp after which the task expires if not started.
- Name
payload- Type
- object
- Description
The data to be processed by the task.
- Name
unique_id- Type
- string
- Description
Unique identifier to prevent duplicate tasks.
- Name
tags- Type
- string | array
- Description
Tags to categorize tasks.
Timing behavior
When specifying execution and expiration timing:
- The expiration time must be after the execution time - an error will be returned if this is not the case
- The specified execution times are earliest possible execution times - actual execution may be delayed due to:
- Rate limits
- Request execution errors and retries
- Network issues or delays
- System load, queue depth, and other factors
- In most cases, the task will be executed within a few seconds of the specified time
Request
curl https://api.taskhook.io/v1/tasks \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"target": {
"url": "https://example.com/process",
"method": "POST",
"headers": {"X-Custom": "value"}
},
"notifications": {
"url": "https://example.com/status",
"events": ["task.completed"]
},
"execute_after": "2024-02-01T12:00:00Z",
"payload": {"key1": "value1"}
}'
Response
{
"id": "task_123",
"status": "queued",
"target": {
"url": "https://example.com/process",
"method": "POST",
"headers": {
"X-Custom": "value"
}
},
"notifications": {
"url": "https://example.com/status",
"events": ["task.completed"]
},
"payload": {
"key1": "value1"
},
"execute_after": "2024-02-01T13:00:00Z",
"created_at": "2024-02-01T12:00:00Z"
}
List all tasks
Retrieve a paginated list of all your tasks. Default limit is 100 tasks per page.
Optional attributes
- Name
status- Type
- string
- Description
Filter tasks by status (queued, processing, completed, failed).
- Name
limit- Type
- integer
- Description
Limit the number of tasks returned (default: 100).
- Name
offset- Type
- integer
- Description
Number of tasks to skip for pagination (default: 0).
Request
curl -G https://api.taskhook.io/v1/tasks \
-H "Authorization: Bearer {token}" \
-d status=completed \
-d limit=10
Response
{
"total": 2,
"tasks": [
{
"id": "task_123",
"status": "completed",
"target": {
"url": "https://example.com/process",
"method": "POST",
"headers": {
"X-Custom": "value"
}
},
"notifications": {
"url": "https://example.com/status",
"events": ["task.completed"]
},
"payload": {
"key1": "value1"
},
"attempts": 1,
"execute_after": "2024-02-01T13:00:00Z",
"created_at": "2024-02-01T12:00:00Z",
"updated_at": "2024-02-01T13:01:00Z",
"last_attempt_at": "2024-02-01T13:01:00Z"
},
{
"id": "task_456",
"status": "queued",
// ...
}
]
}
Retrieve a task
Retrieve a specific task by its ID. Returns the complete task object with all properties.
Request
curl https://api.taskhook.io/v1/tasks/task_123 \
-H "Authorization: Bearer {token}"
Response
{
"id": "task_123",
"status": "completed",
"target": {
"url": "https://example.com/process",
"method": "POST",
"headers": {
"X-Custom": "value"
}
},
"notifications": {
"url": "https://example.com/status",
"events": ["task.completed"]
},
"payload": {
"key1": "value1"
},
"attempts": 1,
"execute_after": "2024-02-01T13:00:00Z",
"expires_at": "2024-02-01T16:00:00Z",
"created_at": "2024-02-01T12:00:00Z",
"updated_at": "2024-02-01T13:01:00Z",
"last_attempt_at": "2024-02-01T13:01:00Z"
}
Cancel a task
Cancel a task that hasn't been processed yet. This action is permanent and cannot be undone.
When a task is cancelled:
- Its status immediately changes to "cancelled"
- Any configured notifications will receive a "task.cancelled" event
- For group tasks, a "group.task_cancelled" event is also sent
Request
curl -X DELETE https://api.taskhook.io/v1/tasks/task_123 \
-H "Authorization: Bearer {token}"
Response
{
"id": "task_123",
"status": "cancelled"
}
Notification Payload Format
When Taskhook sends notifications about task status changes, the payload follows this format:
{
"task_id": "task_123",
"event": "task.completed", // or other event types
"timestamp": "2024-02-01T13:00:00Z",
"status": "completed",
"previous_status": "processing",
"attempt": 1, // Current attempt number if applicable
"target": {
// Original target configuration
"url": "https://example.com/process",
"method": "POST",
"headers": {
"X-Custom": "value"
}
},
"payload": {
// Original task payload
"key1": "value1"
},
"error": {
// Present only for failure events
"code": "ERR_CONNECTION_REFUSED",
"message": "Failed to connect to host",
"status_code": 503 // If applicable
},
"group_info": {
// Present only for group tasks
"total_tasks": 5,
"completed": 3,
"failed": 1,
"remaining": 1
}
}