Events

An event is an object representing a change to a resource that was observed by an event subscription. Event streams rely on the same infrastructure as webhooks, which ensures events are delivered within a minute (on average). This system is designed for at most once delivery, meaning in exceptional circumstances a small number of events may be missing from the stream. For this reason, if your use case requires strong guarantees about processing all changes on a resource and cannot tolerate any missing events, regardless of how rare that might be, we recommend building a fallback polling system that fetches the resource periodically as well. Note that while webhooks cannot be replayed once delivered, events are retrievable from the event stream for 24 hours after being processed.

In general, requesting events on a resource is faster and subject to higher rate limits than requesting the resource itself. Additionally, change events "bubble up" (e.g., listening to events on a project would include when stories are added to tasks in the project, and even to subtasks).

Establish an initial sync token by making a request with no sync token. The response will be a 412 Precondition Failed error - the same as if the sync token had expired.

Subsequent requests should always provide the sync token from the immediately preceding call.

Sync tokens

Sync tokens may not be valid if you attempt to go "backward" in the history by requesting previous tokens, though re-requesting the current sync token is generally safe, and will always return the same results.

When you receive a 412 Precondition Failed error, it means that the sync token is either invalid or expired. If you are attempting to keep a set of data in sync, this signals you may need to re-crawl the data.

Sync tokens always expire after 24 hours, but may expire sooner, depending on load on the service.

Event

An event is an object representing a change to a resource that was observed by an event subscription or delivered asynchronously to the target location of an active webhook.

The event may be triggered by a different user than the subscriber. For example, if user A subscribes to a task and user B modified it, the event’s user will be user B. Note: Some events are generated by the system, and will have null as the user. API consumers should make sure to handle this case.

The resource that triggered the event may be different from the one that the events were requested for or the webhook is subscribed to. For example, a subscription to a project will contain events for tasks contained within the project.

Pay close attention to the relationship between the fields Event.action and Event.change.action. Event.action represents the action taken on the resource itself, and Event.change.action represents how the information within the resource's fields have been modified.

For instance, consider these scenarios:

When at task is added to a project, Event.action will be added, Event.parent will be an object with the id and type of the project, and there will be no change field
When an assignee is set on the task, Event.parent will be null, Event.action will be changed,
Event.change.action will be changed, and new_value will be an object with the user's id and type
When a collaborator is added to the task, Event.parent will be null, Event.action will be changed, Event.change.action will be added, and added_value will be an object with the user's id and type

Property	Type	Description
`action`	string	The type of action taken on the resource that triggered the event. This can be one of `changed`, `added`, `removed`, `deleted`, or `undeleted` depending on the nature of the event.
`change`	object	Information about the type of change that has occurred. This field is only present when the value of the property `action`, describing the action taken on the resource, is `changed`.
`change`.`action`	string	The type of action taken on the field which has been changed. This can be one of `changed`, `added`, or `removed` depending on the nature of the change.
`change`.`added_value`	any	Conditional. This property is only present when the field's `action` is `added` and the `added_value` is an Asana resource. This will be only the `gid` and `resource_type` of the resource when the events come from webhooks; this will be the compact representation (and can have fields expanded with opt_fields) when getting events.
`change`.`field`	string	The name of the field that has changed in the resource.
`change`.`new_value`	any	Conditional. This property is only present when the field's `action` is `changed` and the `new_value` is an Asana resource. This will be only the `gid` and `resource_type` of the resource when the events come from webhooks; this will be the compact representation (and can have fields expanded with opt_fields) when getting events.
`change`.`removed_value`	any	Conditional. This property is only present when the field's `action` is `removed` and the `removed_value` is an Asana resource. This will be only the `gid` and `resource_type` of the resource when the events come from webhooks; this will be the compact representation (and can have fields expanded with opt_fields) when getting events.
`created_at`	string(date-time)	The timestamp when the event occurred.
`parent`	object	For added/removed events, the parent object that resource was added to or removed from. The parent will be `null` for other event types.
`parent`.`gid`	string	Globally unique identifier of the resource, as a string.
`parent`.`resource_type`	string	The base type of this resource.
`parent`.`name`	string	The name of the object.
`resource`	object	The resource which has triggered the event by being modified in some way.
`resource`.`gid`	string	Globally unique identifier of the resource, as a string.
`resource`.`resource_type`	string	The base type of this resource.
`resource`.`name`	string	The name of the object.
`type`	string	Deprecated: Refer to the `resource_type` of the resource. The type of the resource that generated the event.
`user`	object	The user who triggered the event.
`user`.`gid`	string	Globally unique identifier of the resource, as a string.
`user`.`resource_type`	string	The base type of this resource.
`user`.`name`	string	Read-only except when same user as requester. The user’s name.

{
  "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"
  }
}