Follow
Event Subscription API

When an action occurs on a Workfront object that is supported by event subscriptions, you can configure Workfront to send a response to your desired endpoint. This means your integrations can interact with the Workfront API in real time.

The following topics support the Event Subscription API:

Objects Supported by Event Subscriptions

The following Workfront objects are supported by event subscriptions.

  • User
  • Portfolio
  • Program
  • Project
  • Task
  • Issue
  • Template
  • Report
  • Dashboard
  • Company
  • Document
  • Note

Event Subscription Authentication

To create, query, or delete an event subscription, your Workfront user needs the following:

  • An access level of “System Administrator”
  • An apiKey
    Note If your user is already utilizing Workfront’s API, your user should already have an apiKey. You can retrieve the apiKey via the following HTTP request:

Request URL:

[PUT]
https://<HOSTNAME>/attask/api/v7.0/USER?action=getApiKey&username=<USERNAME>&password=<PASSWORD>

Request Headers:

Header Name

Header Value

Content-type

application/json


Response Codes:

Response Code Description
200 (OK) The request was processed successfully, and the existing apiKey for the user should be returned in the response body.
401 (Unauthorized) The server acknowledges the request, but was unable to process it because the requesting apiKey/user does not have access to make this request.

Response Body Example:

 {
"data": {
   "result": "rekxqndrw9783j4v79yhdsakl56bu1jn"
 }
}

NOTE If this is your first time using the Workfront API, then you need to generate an apiKey which you can do via this link:

[PUT]
https://<HOSTNAME>/attask/api/v7.0/USER/generateApiKey?username=<USERNAME>&password=<PASSWORD>

 

Forming the Subscription Resource

The subscription resource contains the following fields.

  • objId (optional)
    • String - The ID of the object of the specified objCode for which events are fired. If this field is not specified, the user receives events for all objects of the specified type.
  • objCode (required)
    • String - The objCode of the object being subscribed to changes. The possible values for objCode are listed in the table below.

      Object

      objCode

      User

      USER

      Portfolio

      PORT

      Program

      PRGM

      Project

      PROJ

      Task

      TASK

      Issue

      OPTASK

      Template

      TMPL

      Report

      PTLSEC

      Dashboard

      PTLTAB

      Company

      CMPY

      Document

      DOCU

      Note

      NOTE

  • eventType (required)
    • String - A value that represents the type of event to which the object is subscribed. The available event types include:
      • CREATE
      • DELETE
      • UPDATE
      • SHARE
  • url (required)
    • String - The URL of the endpoint to which subscription event payloads are sent via HTTP.
  • authToken (required)
    • String - The OAuth2 bearer token used to authenticate with the URL specified in the “URL” field. 

Creating Event Subscription API Requests

After ensuring the user has administrator access and forming the subscription resource, you are ready to create event subscriptions.

Use the following syntax to construct the URL.

Request URL:

[POST] https://<HOSTNAME>/attask/eventsubscription/api/v1/subscriptions

Request Headers:

Header Name

Header Value

Content-type

application/json

Authorization

apiKey value

Request Body Example:

{
"objCode": "PROJ",
"eventType": "UPDATE",
"url": "http://requestb.in/ua5hi2ua",
"authToken": "EauthTokenWorkfrontRocks1234_"
}

Response Codes:

Response Code Description
201 (Created) The event subscription was successfully created.
400 (Bad Request) The URL field of the subscription resource was deemed invalid.
401 (Unauthorized) The apiKey provided was empty or deemed invalid.
403 (Forbidden) The user, which matches the provided apiKey, does not have administrator access.


Passing a subscription resource as the body of a request (with the content-type being “application/json”) results in an event subscription being created for the object specified. A response code of 201 (Created) indicates the subscription was created. A response code other than 201 means the subscription was
NOT created.

NOTE The “Location” response header contains the URI of the newly created event subscription.

Response Headers Example:

Response Headers Example
Content-Length
0
Date
Wed, 05 Apr 2017 21:23:33 GMT
Location
https://<HOSTNAME>/attask/eventsubscription/api/v1/subscriptions/750a636c-5628-48f5-ba26-26b7ce537ac2
Server  
Apache-Coyote/1.1

Response Body Example:   N/A 

Querying Event Subscriptions

When querying Workfront’s HTTP use the GET method. There are two ways to query for event subscriptions:

Query All Events Subscriptions

You can query all events subscriptions for a customer as specified by the apiKey value. The request syntax for listing all event subscriptions for a specific customer is as follows:

Request URL:

[GET] https://<HOSTNAME>/attask/eventsubscription/api/v1/subscriptions/list

Request Headers:

Header Name

Header Value

Authorization

apiKey value


Response Codes:

Response Code Description
200 (OK) The request returned with all event subscriptions found for the customer matching the provided apiKey.
401 (Unauthorized) The apiKey provided was empty.
403 (Forbidden) The user, which matches the provided apiKey, does not have administrator access.

Response Headers Example:

Response Header Example
Content-Type
application/json;charset=UTF-8
Date
Wed, 05 Apr 2017 21:29:32 GMT
Server
Apache-Coyote/1.1
Transfer-Encoding
chunked

 

Response Body Example:

[
 {
   "id": "37c4bcf5-e0b5-4256-aba3-a51cba7bf997",
   "customerId": "504f9640000013401be513579fbebffa",
   "objId": "ObjId1234",
   "objCode": "TASK",
   "url": "http://test.test.net/test/1234",
   "eventType": "UPDATE",
   "authToken": "auth_token"
 },
 {
   "id": "750a636c-5628-48f5-ba26-26b7ce537ac2",
   "customerId": "504f9640000013401be513579fbebffa",
   "objId": null,
   "objCode": "PROJ",
   "url": "http://requestb.in/ua5hi2ua",
   "eventType": "UPDATE",
   "authToken": "authTokenWorkfrontRocks1234_"
 }
]

Query By the Event Subscription ID

You can query for event subscriptions by the event subscription’s ID. The request syntax for listing event subscriptions is as follows:

Request URL:

[GET] https://<HOSTNAME>/attask/eventsubscription/api/v1/subscriptions/<SUBSCRIPTION ID>

Request Headers:

Header Name

Header Value

Authorization

apiKey value

Response Codes:

Response Code Description
200 (OK) The request returned with the event subscription matching the provided subscription ID.
401 (Unauthorized) The apiKey provided was empty.
403 (Forbidden) The user, which matches the provided apiKey, does not have administrator access.

Response Headers Example:

Response Header Example
Content-Type
application/json;charset=UTF-8
Date
Wed, 05 Apr 2017 21:31:39 GMT
Server
Apache-Coyote/1.1
Transfer-Encoding
chunked


Response Body Example:

{
 "id": "750a636c-5628-48f5-ba26-26b7ce537ac2",
 "customerId": "504f9640000013401be513579fbebffa",
 "objId": null,
 "objCode": "PROJ",
 "url": "http://requestb.in/ua5hi2ua",
 "eventType": "UPDATE",
 "authToken": "authTokenWorkfrontRocks1234_"
}

Deleting Event Subscriptions

When deleting Workfront’s HTTP use the DELETE method. The request syntax for deleting a single event subscription by subscription ID is as follows:

Request URL:

[DELETE] https://<HOSTNAME>/attask/eventsubscription/api/v1/subscriptions/<SUBSCRIPTION ID> 

Request Headers:

Header Name

Header Value

Authorization

User’s apiKey

Response Codes:

Response Code

 Description
204 (No Content) The server successfully removed the event subscription matching the provided subscriptionID.
401 (Unauthorized) The apiKey provided was empty.
403 (Forbidden) The User which matches the provided apiKey does not have administrator access.
404 (Not Found) The server was unable to find an event subscription matching the subscriptionID provided for deletion.


Response Headers Example:

Response Header Example
Date
Wed, 05 Apr 2017 21:33:41 GMT
Server
Apache-Coyote/1.1

Response Body Example: N/A

Example of an Event Payload

The payload that a user receives varies depending on the object type, but there is a consistent format for which those varying payloads are delivered.

The eventType, subscriptionId, and fields properties remain consistent across all event payloads, but the values contained within the fields property varies between different objects and object types.

Following is an example payload for a PROJ object type:

{
 "eventType": "UPDATE",
 "subscriptionId": "750a636c-5628-48f5-ba26-26b7ce537ac2",
 "fields": {
   "objCode": "PROJ",
   "entryDate": "2017-03-29T10:18:54.697-0600",
   "lastUpdateDate": "2017-04-20T10:07:55.695-0600",
   "accessorIDs": [],
   "groupID": "504f9640000015db5e89a487dc1c699b",
   "sponsorID": null,
   "plannedCompletionDate": "2017-03-29T09:00:00.000-0600",
   "description": null,
   "enteredByID": "504f9641000015eeabd95183bebb39b4",
   "ownerID": "504f9641000015eeabd95183bebb39b4",
   "templateID": null,
   "priority": 2.0,
   "companyID": null,
   "portfolioID": null,
   "referenceNumber": 1007.0,
   "lastUpdatedByID": "504f9641000015eeabd95183bebb39b4",
   "name": "PROJECT NAME",
   "customerID": "504f9640000013401be513579fbebffa",
   "currency": null,
   "ID": "58dbde6e0000013092a25a134c72be9d",
   "categoryID": null,
   "status": "CUR",
   "parameterValues": {}
 }
}