[New] Events and webhooks for goals

English Forum Developers & API Changelog
, , ,
1

We’re excited to announce new API features that improve the ability to track and audit changes to goals. Starting March 4th, Asana will begin emitting event objects for goals, providing apps programmatic visibility into changes.

While events allow apps to poll for changes, we have also added goal events to our webhooks infrastructure for apps that need to be immediately notified about changes in Asana.

Usage

You can access goal events by using the existing events API. For example, here is how you would use the GET events on resource route to fetch events for a goal:

  1. Establish an initial sync token by making a request with no sync token:
    GET /events?resource=<goal-GID>
  2. The response will be a 412 Precondition Failed. They body of the error will provide a sync token to use in your subsequent request:
{
  "errors": [
    {
      "message": "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": "4647de3a0f78f6a74e4ef066ef30a4fe:0"
}

(Note: this is also the error you get for an expired or invalid sync token)

  1. Make another request using the sync token from the error body:
    GET /events?resource=<goal-GID>&sync=4647de3a0f78f6a74e4ef066ef30a4fe:0

  2. Use the unique sync token in each response in your next request

  3. Events can be noisy. Consider using opt_fields (by passing a comma-separated list) to specify the types of changes that are of interest

The following goal events will be emitted:

  • Goal added/removed from domain/team
  • Goal deleted/undeleted
  • Goal property changed, including:
    • Name
    • Due date
    • Start date
    • Owner
    • Status
    • Description
    • Metric
    • Time period
    • Followers
  • Attachment added/deleted
  • Member added/removed
  • Project/task/portfolio/goal added/removed from goal
  • Story added/removed from goal

Here’s an example of an API response for a name change event:

[
  {
    "user": {
      "gid": "75603",
      "resource_type": "user",
      "name": "Sashimi Rosenstein"
    },
    "created_at": "2024-01-02T18:15:29.907Z",
    "type": "goal",
    "action": "changed",
    "resource": {
      "gid": "2420428",
      "resource_type": "goal",
      "owner": {
        "gid": "75603",
        "resource_type": "user",
        "name": "Sashimi Rosenstein"
      },
      "name": "testing"
    },
    "parent": null,
    "change": {
      "field": "name",
      "action": "changed"
    }
  }
]

Timeline for Launch

We will start the incremental rollout on March 4th, beginning with 10% of domains and increasing to 100% over the course of the day. Unless there are any unexpected issues, goal events and webhooks will be available to everyone by March 5th.

Reason for change

We chose to build events for goals for 2 primary reasons:

  1. Goal events are needed by customers in regulated industries that have audit compliance requirements
  2. We strive for API parity with the Asana web product. By making the Asana work graph programmatically accessible via the API, developers can build more powerful apps that integrate Asana data with the other tools customers rely on

Questions & Feedback

Our engineering team behind goals, alongside the Developer Relations team, will be actively monitoring this topic. This is your direct line to those who have crafted the feature, so please provide feedback, report any issues you encounter, and ask questions. Your input is valuable as it helps us continue to refine and improve the developer experience.

Happy coding!

Best,

Asana DevRel

P.S.: To stay updated on Asana API changes, you can create a customizable subscription to the API changelog forum category. Instructions for doing so can be found in this post.

March 4th Update:
We have rolled this out to 100% of domains

3 Likes
2

Nice, @Jeff_Schneider and team! :clap:

4 Likes
4

Hey @Jeff_Schneider,

Is there a way to be notified when a new goal is created in a team or project? It appears the usage documented here is only for existing goals.

5

See the first bullet point above:

6

@Phil_Seeman what resource ID do I use?

The events API says the resource can be a task, project, or goal. I need it to notify me of all goals created.

7

I think that’s actually an inaccuracy in the documentation; depending on the specific operation being done, the resource can at times be a team or workspace.

In this case, I’m guessing based on experience with other objects that you can set the resource to a workspace or team gid, set a webhook filter resource_type to “goal” and filter action to “added”.

In other words, your webhook would contain a structure like

  { 
    "resource": workspaceGid,
    "target": [your target],
    "filters": {
      "resource_type": "goal",
      "action": "added"
    }
  }

As I said, I haven’t tried this for goals yet, but the above syntax is analogous to how you set a webhook to obtain, say, all project adds within a workspace.

1 Like
8

Hey @Phil_Seeman,

Tried that and this is the error:

{
  "errors": [
    {
      "error": "invalid_filters_for_larger_scoped_webhooks",
      "message": "Webhooks for larger scoped resources must have at least one filter and all filters must be in our whitelist.",
      "user_message": "Webhooks for larger scoped resources must have at least one filter and all filters must be in our whitelist.",
      "help": "For more information on API status codes and how to handle them, read the docs on errors: https://developers.asana.com/docs/errors"
    }
  ]
}

I tried having the resource be the team and no go.
I also tried having the resource be the project, but even if I associate a goal with a project, it does not fire.

9

Oh, darn, they must not support what I was hoping.

@Jeff_Schneider what say you? No go on setting a workspace- or team-level webhook to be notified of new goals in that workspace/team?

10

@Marketing35 & @Phil_Seeman – thank you for flagging this issue. We looked into the code and confirmed that the initial API implementation of this work did not include adding goal events to our webhook filtering infrastructure.

The eng team made the fix and you should now be able to see goal added/removed events by including a filter for the goal resource type and event action (changed, added, removed, deleted, undeleted) in your webhook request. Please let us know if this is not the case.

2 Likes