Follow
Event Subscription API

 

The highlighted information on this page refers to functionality not yet generally available. It is available only in the Preview Sandbox environment.

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.

  • Assignment
  • Company
  • Dashboard
  • Document
  • Expense
  • Hour
  • Issue
  • Note
  • Portfolio
  • Program
  • Project
  • Report
  • Task
  • Template
  • Timesheet
  • User

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

      Assignment

      ASSGN

      Company 

      CMPY

      Dashboard PTLTAB

      Document

      DOCU 

      Expense

      EXPNS

      Hour

      HOUR
      Issue

      OPTASK

       Note  NOTE

      Portfolio

      PORT

      Program

      PRGM

      Project

      PROJ

      Report

      PTLSEC

      Task

      TASK

      Template

      TMPL

      Timesheet TSHEET
      User USER
  • 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

Examples of Event Payloads

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.

For example, the following properties remain consistent across all event payloads:

  • eventType
  • subscriptionId
  • oldState
  • newState
  • eventTime

Although consistent in format, the values contained within the properties vary between different objects and object types.

Samples of payloads for an UPDATE event and a CREATE event are shown below. Notice in the UPDATE example the oldState and newState objects are the same, while in the CREATE example the oldState object is empty (not NULL).

The following is an example payload for an UPDATE event:

{
   "eventType": "UPDATE",
   "subscriptionId": "8a0d839d5ef32c9a015ef336a5ed0002",
   "eventTime": {
       "nano": 998000000,
       "epochSecond": 1507319336
   },
   "newState": {
       "ID": "59d7ddf7000002322d791eb08bafddfb", 
       "name": "EventSub Test updated",
       "objCode": "PROJ",
       "entryDate": "2017-10-06T13:48:07.776-0600",
       "accessorIDs": [
           "544820df0000142362741fc0c368de19"
       ],
       "lastUpdateDate": "2017-10-06T13:48:56.980-0600",
       "groupID": "544820df0000140f6a9c1faa7cacadd3",
       "sponsorID": null,
       "description": null,
       "plannedCompletionDate": "2017-10-06T09:00:00.000-0600",
       "enteredByID": "544820df0000142362741fc0c368de19",
       "ownerID": "544820df0000142362741fc0c368de19",
       "templateID": null,
       "priority": 0,
       "companyID": null,
       "portfolioID": null,
       "referenceNumber": 1894,
       "lastUpdatedByID": "544820df0000142362741fc0c368de19",
       "customerID": "544820df0000135b7719dcca654391f6",
       "currency": null,
       "categoryID": null,       "status": "CUR",       "parameterValues": {}    },    "oldState": {        "ID": "59d7ddf7000002322d791eb08bafddfb",        "name": "EventSub Test 180fd595-63fb-4fa9-bd47-58bf6e53d964",        "objCode": "PROJ",        "entryDate": "2017-10-06T13:48:07.776-0600",        "accessorIDs": [            "544820df0000142362741fc0c368de19"        ],        "lastUpdateDate": "2017-10-06T13:48:07.792-0600",        "groupID": "544820df0000140f6a9c1faa7cacadd3",        "sponsorID": null,        "description": null,        "plannedCompletionDate": "2017-10-06T09:00:00.000-0600",        "enteredByID": "544820df0000142362741fc0c368de19",        "ownerID": "544820df0000142362741fc0c368de19",        "templateID": null,        "priority": 0,        "companyID": null,<        "portfolioID": null,        "referenceNumber": 1894,        "lastUpdatedByID": "544820df0000142362741fc0c368de19",        "customerID": "544820df0000135b7719dcca654391f6",        "currency": null,        "categoryID": null,        "status": "CUR",        "parameterValues": {}    } }

Following is an example payload for a CREATE event:

{
 "eventType": "CREATE",
 "subscriptionId": "4028e3815ebf03a7015ebfa53b6d0002",
 "eventTime": {
     "nano": 232000000,
     "epochSecond": 1506453831
 },
 "newState": {
     "ID": "59caa946000000e07b0afc3383230c67",
     "name": "EventSub Test fe16d470-0a40-4290-92f4-6a0389fb536c",
     "objCode": "PROJ",
     "entryDate": "2017-09-26T13:23:50.746-0600",
     "accessorIDs": ["544820df0000142362741fc0c368de19"],
     "lastUpdateDate": "2017-09-26T13:23:50.927-0600",
     "groupID": "544820df0000140f6a9c1faa7cacadd3",
     "sponsorID": null,
     "description": null,
     "plannedCompletionDate": "2017-09-26T09:00:00.000-0600",
     "enteredByID": "544820df0000142362741fc0c368de19",
     "ownerID": "544820df0000142362741fc0c368de19",
     "templateID": null,
     "priority": 0,
     "companyID": null,
     "portfolioID": null,
     "referenceNumber": 1750,
     "lastUpdatedByID": "544820df0000142362741fc0c368de19",
     "customerID": "544820df0000135b7719dcca654391f6",
     "currency": null,
     "categoryID": null,
     "status": "CUR",
     "parameterValues": {}
 },
 "oldState": {}
}

ƒ