Workspace events

📘

Access requirements

Currently, access to this API is exclusively available through a service account in an Enterprise+ domain.

Overview

Asana's workspace-level event streams provide continuous updates on objects within Asana. These event streams can be particularly useful for data loss prevention (DLP), e-discovery, and archiving purposes.

Whenever changes occur to the included objects, Asana generates events that indicate whether an object has been added, changed, deleted, or undeleted. Notably, workspace-level events are sent even when access control would typically restrict them.

This feature extends Asana’s existing events API and includes additional resources and actions, detailed in our webhooks guide.

Prerequisites

Workspace-level event streams can only be initiated using a service account.

API reference

Endpoint

Request parameters

Response

The following is an example response:

{
  "data": [
    {
      "action": "changed",
      "change": {
        "action": "changed",
        "added_value": {
          "gid": "12345",
          "resource_type": "user"
        },
        "field": "assignee",
        "new_value": {
          "gid": "12345",
          "resource_type": "user"
        },
        "removed_value": {
          "gid": "12345",
          "resource_type": "user"
        }
      },
      "created_at": "2012-02-22T02:06:58.147Z",
      "parent": {
        "gid": "12345",
        "resource_type": "task",
        "name": "Bug Task"
      },
      "resource": {
        "gid": "12345",
        "resource_type": "task",
        "name": "Bug Task"
      },
      "type": "task",
      "user": {
        "gid": "12345",
        "resource_type": "user",
        "name": "Greg Sanchez"
      }
    }
  ],
  "sync": "de4774f6915eae04714ca93bb2f5ee81",
  "has_more": true
}

Note: For more details regarding events, including structure and individual property details, visit our API reference.

Each item in the data array of the API response indicates whether a new object was added, updated, deleted, or undeleted.

To get the current state of any particular object, make requests against their respective API endpoints. For example:

• For a task, use task-related endpoints
• For a team, use team-related endpoints

Currently included events encompass those described in this section of our webhooks guide, excluding "Workspace - changed."

Example workflow

To get started with workspace-level event streams:

1. Make the initial request to GET workspaces/{workspace_gid}/event
2. The HTTP response will return a status code of 412 Precondition Failed, along with a sync token. The message will be in the following format:

"Sync token invalid or too old. If you are attempting to keep resources in sync, you must 
fetch the full dataset for this query now and use the new sync token for the next sync. 
Sync: fd511a29f359c76298284ce9236e4f27:0"

3. Use the provided sync token in a subsequent request to GET workspaces/{workspace_gid}/events?sync={sync_token}
4. For all subsequent requests, continue to use the sync token from the previous response

Event limitations

Maximum event retrieval

Asana restricts each sync token to a maximum of 1,000 events. If there are more than 1,000 events for a given workspace, the response will include has_more: true (as shown above), indicating that additional events are available to retrieve.

Current state retrieval

Asana's API currently provides the most recent "version" of an object, meaning you cannot request past versions of an object, including those that may have generated events. Therefore:

• If an object has been edited, you will receive the most recent version of that object at the time you pull the event
• While events include certain fields like name, most updates will require an additional call to obtain the current state of the field.

Polling frequency recommendation

To ensure you capture all events, we recommend polling at least every few minutes. If more than 4 hours pass without a request, events are likely to be lost.

Timing of event availability

There may be a brief interval between when a change occurs in Asana and when it becomes available through events. This interval typically averages under a minute but may extend to ten minutes during periods of high activity or longer during outages.

Troubleshooting

Handling failure

If the sync token has expired, events may be lost, as the new token will not include events older than 4 hours. This can occur if no requests are made within that timeframe.

Additionally, an outage shorter than 4 hours may also result in missed events if the app does not poll quickly enough to compensate for any gaps in event requests. We recommend polling every few minutes to mitigate this risk.

Understanding added events and resource status

An event with the action type added does not necessarily indicate that the resource itself is new. Instead, it signifies that the resource has been added to a parent entity (for example, a task added to a project).

Identifying comment-related events

Stories take on the following format:

{
  // ...
  "type": "story",
  "resource": {
    "resource_type": "story",
    "type": "comment"
  }
}

The sync token expires after 4 hours of inactivity. If no API call is made during this period, the token will expire. In this case, a subsequent API call will return a 412 HTTP status code along with a new token.