REST Hooks

REST Hooks answer the question: What events can I listen for coming out of actiTIME?

Rather than having your system continuously poll to find out when there is new information to trigger from, we allow you to register a URL which we will call when these events occur. Whenever an event you have subscribed to occurs, for example a new task being created in actiTIME, we will send a HTTP POST to your URL with information about that event for your system to act upon.

REST Hooks is a collection of patterns that treat webhooks like subscriptions. These subscriptions are manipulated via a REST API just like any other resource.

More info on REST Hooks is available at http://resthooks.org

 
The following requests are supported for operations with REST Hooks subscriptions via actiTIME API:

POST/hooks
POST/hooks/unsubscribe
DELETE/hooks/{id}
GET/hooks

Events List

Usually event is an action on an object.

Supported actions: create, update, delete.
Supported objects: task, project, customer, user, department, time zone group.

You can subscribe to a variety of events, for example: creating of a new department, updating the task details, deleting a project, etc.

Events that a user can be subscribed to are listed in the table below.

Event Description
* Subscription to all supported events.
create Subscription to all events of creating the supported objects.
update Subscription to all events of updating the supported objects.
delete Subscription to all events of deleting the supported objects.
task Subscription to all events of the supported actions on all available tasks.
project Subscription to all events of the supported actions on all available projects.
customer Subscription to all events of the supported actions on all available customers.
user Subscription to all events of the supported actions on all users.
department Subscription to all events of the supported actions on all departments.
timeZoneGroup Subscription to all events of the supported actions on all time zone groups.
Combination of actions and objects, e.g.:
task.create, department.delete
Subscription to an event of specified action on a specified object.
The following format must be used: “object.action”.

Subscription Properties

The REST Hook subscription properties are listed in the table below.

Property Description
id Unique REST Hook subscription identifier.
event Event for which subscription is made.
See also the ‘Events List’ section.
filter Filtering parameter. Supported only for tasks, projects and customers related events.
enabled Status of REST Hook. Cannot be changed. Possible values: true, false.

If ‘true’, then the subscription is enabled (whenever the event occurs, the corresponding data are sent to the ‘target_url’).
If ‘false’, then the subscription is disabled (no attempts to send the data to the ‘target_url’ are done even if the event occurs).

lastHttpStatus The last HTTP status code returned from ‘target_url’ while trying to send the data there after occuring the event.
lastHttpError Description of the last error returned from ‘target_url’ while trying to send the data there after occuring the event.
lastHttpCall The last date when there was an attempt to send the data to ‘target_url’ after occuring the event.
userId Unique identifier of a subscribed user.
target_url The URL which the data are sent to when the event occurs.

Required Permissions

To be able to work with REST Hooks subscriptions, the user should have:

  • the ‘Manage Scope of Work’ permission;
  • access to the entire Scope of Work.

Create Subscription

Use the following request to create a new subscription:

POST/hooks

Request body should include the following parameters:

  • event – the event name that you want to be told about, optional (if not specified, then ‘*’ value is used);
  • filter – the IDs of the objects you want to be told about, optional (if not specified, then no filter is applied);
  • target_url – the URL which you want our API to POST to when this event occurs, mandatory.

Please note:

1) Filters are supported only for the following events: task, project, customer (and related create / update / delete events).

Supported filters for task events: taskIds, projectIds, customerIds.
Supported filters for project events: projectIds, customerIds.
Supported filters for customer events: customerIds.

Example:

{
  "event": "task.update",
  "filter": {
    "customerIds": "1,2",
    "projectIds": "3,4",
    "taskIds": "10,25",
  },
  "target_url": "<Target URL>"
}

Use the example filter to be notified about all updates of the following tasks:

  • tasks with IDs 10 and 25;
  • tasks of projects with IDs 3 and 4;
  • tasks of customers with IDs 1 and 2.

2) You may register more than one ‘target_url’ for a given event: when the event occurs each of the registered target URLs will be called with the event data. You may register the same ‘target_url’ for different events. You may not, however, register the same ‘target_url’ more than once for one given event: if you try, you will receive a 409 error code.

 
Returned response includes:

  • ‘event’, ‘filter’ and ‘target_url’ specified in request body;
  • unique ID of created subscription.

Example Request:

curl -X POST "<actiTIME URL>/api/v1/hooks" -H "accept: application/json; charset=UTF-8" -H "Content-Type: application/json" -u "username:password" -d "{ \"event\": \"task.create\", \"filter\": { \"customerIds\": \"7\", \"projectIds\": \"13\" }, \"target_url\": \"<Target URL>\"}"

Example Response:

{
  "id": 8,
  "event": "task.create",
  "filter": "customerIds=7&projectIds=13",
  "target_url": "<Target URL>"
}

More info on using this request is available in our detailed documentation

Delete Subscription

Use one of the following requests to delete a REST Hook subscription:

POST/hooks/unsubscribe
DELETE/hooks/{id}

 
While using the POST/hooks/unsubscribe request, the ‘target_url’ of subscriptions to be deleted must be specified in body request. After executing this request all subscriptions with specified ‘target_url’ will be deleted.

Example Request:

curl -X POST "<actiTIME URL>/api/v1/hooks/unsubscribe" -H "accept: application/json; charset=UTF-8" -H "Content-Type: application/json" -u "username:password" -d "{ \"target_url\": \"<Target URL>\"}"

 
While using the DELETE/hooks/{id} request, the ‘id’ of a subscription to be deleted must be specified. After executing this request the subscription with specified ‘id’ only will be deleted.

Example Request:

curl -X DELETE "<actiTIME URL>/api/v1/hooks/10" -H "accept: application/json; charset=UTF-8" -u "username:password"

 
For both requests the 204 status code is returned if operation is successful. The response body is empty.

If the operation has failed, an error code is returned.

More info on using these requests is available in our detailed documentation

Retrieve List of Subscriptions

Use the following request to retrieve a list of REST Hook subscriptions with their properties:

GET/hooks

Example Request:

curl -X GET "<actiTIME URL>/api/v1/hooks" -H "accept: application/json; charset=UTF-8" -u "username:password"

Example Response:

{
    "id": 1,
    "event": "task.create",
    "filter": "projectIds=15",
    "enabled": true,
    "lastHttpStatus": 200,
    "lastHttpError": null,
    "lastHttpCall": "2019-05-14",
    "userId": 1,
    "target_url": "<Target URL>"
  },
  {
    "id": 3,
    "event": "user.delete",
    "filter": null,
    "enabled": true,
    "lastHttpStatus": 200,
    "lastHttpError": null,
    "lastHttpCall": "2019-05-14",
    "userId": 1,
    "target_url": "<Target URL>"
  }

More info on using this request is available in our detailed documentation

Errors Processing

When your ‘target_url’ is POSTed to after occuring the event, our system will react in different ways depending on how your system responds:

  • If we get a status code which is between 200-299, then we have a successful call.
  • If we get a status code which is between 300-399 or 410 status code, then we set the ‘enabled’ property of a subscription to ‘false’ (the subscription is being disabled). If a new subscription’s event has occurred, no attempts to send the data will be made. The ‘enabled’ property of a subscription cannot be changed, so you have to create a new subscription to the event if you want to get the event data again.
  • If we get 413 status code (Too Big Payload), then we gradually reduce the number of sent events (maximum number is 1000). If 10 events are sent and we still get 413 status code, then no further attempt to send this event’s data again will be made. However, if a new subscription’s event has occurred, this new event’s data will be sent.
  • If we get 500 status code, we will try to resend the data 5 times (intervals between the attempts are 5s, 30s, 5min, 30min, 1h).

It is your responsibility to make sure that once registered, your target URL is successfully responding.

Events Data

JSON with the event data which is sent to target URL after occuring the event includes:

  • event name (for example: create, customer.update, user.delete);
  • properties of an object which are usually returned via API calls (for example, properties of a task).

Please note that several events’ data can be sent in one array. Maximum number of sent events in one array is 1000.

Read more about objects’ properties available via API at the following sections:

Example Response:

  
{
        "event.name": "task.delete",
        "id": 143,
        "name": "Interviews",
        "created": 1557832276000,
        "status": "open",
        "workflowStatusId": 1,
        "typeOfWorkId": 3,
        "deadline": null,
        "estimatedTime": null,
        "customerId": 10,
        "projectId": 24
  }