URL Groups

URL Groups allow you to bundle multiple endpoint URLs under a single label. Instead of sending a task to a specific URL, you can send it to a URL Group, and Taskhook will handle routing it to the endpoints in that group. Use URL Groups for pub/sub patterns and service discovery.

Understanding URL Groups

URL Groups provide message routing and service discovery capabilities in Taskhook. Similar to topics in Kafka or exchanges in RabbitMQ, URL Groups let you route messages to multiple endpoints without coupling senders to receivers.

POST/v1/url-groups

Create a URL Group

This endpoint creates a new URL Group for routing tasks to multiple endpoints.

Required attributes

Name
name
Type
string
Description
Unique identifier for referencing this URL Group.
Name
urls
Type
array
Description
Initial list of endpoint URLs.

Optional attributes

Name
description
Type
string
Description
Human-readable description of the URL Group's purpose.

Request

POST

/v1/url-groups

curl https://api.taskhook.io/v1/url-groups \
  -H "Authorization: Bearer {token}" \
  -d '{
    "name": "order-processors",
    "description": "Order processing service endpoints",
    "urls": [
      "https://orders-1.example.com/process",
      "https://orders-2.example.com/process"
    ],
  }'

Response

{
  "id": "ug_123abc",
  "name": "order-processors",
  "description": "Order processing service endpoints",
  "urls": [
    "https://orders-1.example.com/process",
    "https://orders-2.example.com/process"
  ],
  "created_at": "2024-01-30T12:00:00Z",
  "updated_at": "2024-01-30T12:00:00Z"
}

GET/v1/url-groups

List all URL Groups

Retrieves a list of all URL Groups in your account.

Optional query parameters

Name
limit
Type
integer
Description
Maximum number of URL Groups to return (default: 50, max: 100).
Name
offset
Type
integer
Description
Number of URL Groups to skip (default: 0).

Request

GET

/v1/url-groups

curl https://api.taskhook.io/v1/url-groups \
  -H "Authorization: Bearer {token}"

Response

{
  "data": [
    {
      "id": "ug_123abc",
      "name": "order-processors",
      "description": "Order processing service endpoints",
      "urls": [
        "https://orders-1.example.com/process",
        "https://orders-2.example.com/process"
      ],
      "created_at": "2024-01-30T12:00:00Z",
      "updated_at": "2024-01-30T12:00:00Z"
    },
    {
      "id": "ug_456def",
      "name": "notification-services",
      "description": "Notification delivery endpoints",
      "urls": [
        "https://notifications.example.com/send"
      ],
      "created_at": "2024-01-30T12:00:00Z",
      "updated_at": "2024-01-30T12:00:00Z"
    }
  ],
  "total": 2,
  "limit": 50,
  "offset": 0
}

GET/v1/url-groups/:id

Get a URL Group

Retrieves a specific URL Group by its ID.

Required parameters

Name
id
Type
string
Description
Unique identifier of the URL Group.

Request

GET

/v1/url-groups/:id

curl https://api.taskhook.io/v1/url-groups/ug_123abc \
  -H "Authorization: Bearer {token}"

Response

{
  "id": "ug_123abc",
  "name": "order-processors",
  "description": "Order processing service endpoints",
  "urls": [
    "https://orders-1.example.com/process",
    "https://orders-2.example.com/process"
  ],
  "created_at": "2024-01-30T12:00:00Z",
  "updated_at": "2024-01-30T12:00:00Z"
}

PATCH/v1/url-groups/:id

Update a URL Group

Updates an existing URL Group's attributes.

Required parameters

Name
id
Type
string
Description
Unique identifier of the URL Group to update.

Optional attributes

Name
name
Type
string
Description
New name for the URL Group.
Name
description
Type
string
Description
Updated description of the URL Group.
Name
urls
Type
array
Description
New list of endpoint URLs.

Request

PATCH

/v1/url-groups/:id

curl https://api.taskhook.io/v1/url-groups/ug_123abc \
  -X PATCH \
  -H "Authorization: Bearer {token}" \
  -d '{
    "description": "Updated order processing endpoints",
    "urls": [
      "https://orders-1.example.com/process",
      "https://orders-2.example.com/process",
      "https://orders-3.example.com/process"
    ]
  }'

Response

{
  "id": "ug_123abc",
  "name": "order-processors",
  "description": "Updated order processing endpoints",
  "urls": [
    "https://orders-1.example.com/process",
    "https://orders-2.example.com/process",
    "https://orders-3.example.com/process"
  ],
  "created_at": "2024-01-30T12:00:00Z",
  "updated_at": "2024-01-30T13:00:00Z"
}

POST/v1/url-groups/:id/urls

Add URL to Group

Adds a new URL to an existing URL Group. This endpoint is designed for safe registration of new services.

Required parameters

Name
id
Type
string
Description
Unique identifier of the URL Group.

Required attributes

Name
url
Type
string
Description
The URL to add to the group.

Request

POST

/v1/url-groups/:id/urls

curl https://api.taskhook.io/v1/url-groups/ug_123abc/urls \
  -H "Authorization: Bearer {token}" \
  -d '{
    "url": "https://orders-3.example.com/process"
  }'

Response

{
  "id": "ug_123abc",
  "name": "order-processors",
  "description": "Order processing service endpoints",
  "urls": [
    "https://orders-1.example.com/process",
    "https://orders-2.example.com/process",
    "https://orders-3.example.com/process"
  ],
  "created_at": "2024-01-30T12:00:00Z",
  "updated_at": "2024-01-30T13:00:00Z"
}

DELETE/v1/url-groups/:id/urls

Remove URL from Group

Removes a specific URL from a URL Group. This endpoint is designed for safe deregistration of services.

Required parameters

Name
id
Type
string
Description
Unique identifier of the URL Group.

Required attributes

Name
url
Type
string
Description
The URL to remove from the group.

Request

DELETE

/v1/url-groups/:id/urls

curl https://api.taskhook.io/v1/url-groups/ug_123abc/urls \
  -X DELETE \
  -H "Authorization: Bearer {token}" \
  -d '{
    "url": "https://orders-3.example.com/process"
  }'

Response

{
  "id": "ug_123abc",
  "name": "order-processors",
  "description": "Order processing service endpoints",
  "urls": [
    "https://orders-1.example.com/process",
    "https://orders-2.example.com/process"
  ],
  "created_at": "2024-01-30T12:00:00Z",
  "updated_at": "2024-01-30T13:00:00Z"
}

DELETE/v1/url-groups/:id

Delete a URL Group

Permanently deletes a URL Group. This action cannot be undone.

Required parameters

Name
id
Type
string
Description
Unique identifier of the URL Group to delete.

Request

DELETE

/v1/url-groups/:id

curl https://api.taskhook.io/v1/url-groups/ug_123abc \
  -X DELETE \
  -H "Authorization: Bearer {token}"

Response

{
  "deleted": true,
  "id": "ug_123abc"
}

Using URL Groups

To send tasks to a URL Group, reference it by name instead of specifying a callback URL:

{
  "target": "order-processors",
  "payload": {
    "order_id": "123",
    "action": "process"
  }
}

For schedules and batches, include it in the task template:

{
  "task_template": {
    "target": "order-processors",
    "payload": {
      "type": "daily_processing"
    }
  }
}