Upcoming webhook improvements

Hello all! I have perhaps the most exciting news I’ve ever announced on this forum—the API team at Asana is now working on a number of webhook improvements! Ever since we launched the search API last year, webhooks has been the number one feature request/source of developer pain. (In fact, even before we launched the search API it was mostly a toss-up between the two.) After lots of investigation and design, we’re planning on three major improvements that will make Asana’s webhooks easier and more powerful.

A quick note: while we are actively working on these improvements and have an internal timeline, we don’t yet have a launch date for all these features. However, due to some technical constraints, you may observe these features (in a non-breaking way) before their official launch (such as new fields being included in webhook bodies). Now, to the good stuff!

  • Richer webhook events — We’re going to include more information in webhook events so that clients listening for webhooks can have a much better understanding of what actually changed in webhooks. Specifically, events will indicate what field on the object changed. No more fetching all the stories on the task to see what changed most recently—the webhook will tell you up-front. This also applies to events fetched in event streams.
  • Filters on webhook events — You’ll be able to define “filters” on your webhooks so that they only deliver the events you care about. No more dealing with a constant stream of noise when you only care about assignees and custom fields changing. Webhooks can have multiple filters to permit multiple kinds of events through a single subscription.
  • Webhooks with larger scopes (and new events) — Currently you can only create webhooks on tasks, projects, and tags. We’re going to expand that to include teams and workspaces so your app can learn about changes at higher levels. As a consequence of this, we’ll be introducing new events like “project created” and “user added to team.” Webhooks at larger scopes will be required to have certain filters on them, though, so you won’t be able to make high-volume subscriptions like “every change on every task in this organization.”

We hope you’re as excited about these changes as we are! We’ll be sharing more information in the coming weeks, but feel free to leave comments and questions here. Please also let us know what you think in this poll!

On a scale from 1 to 5, how excited are you about these improvements?

  • 1 - I strongly dislike these changes. This is bad for the API.
  • 2 - I dislike these changes. I think there are different improvements you should be making.
  • 3 - I’m indifferent to these changes.
  • 4 - I like these changes. They’ll have direct, positive impact on my app.
  • 5 - I love these changes! I can’t wait to start using them!

0 voters

5 Likes

I’m really looking forward for this feature. Do you have a ETA?

1 Like

Looks like the new webhook changes are breaking our integration. We expected this format as used in the documentation:

{
“resource”: 1337,
“parent”: null,
“created_at”: “2013-08-21T18:20:37.972Z”,
“user”: 1123,
“action”: “changed”,
“type”: “task”
}

And, now we’re getting this:
[
{
“user”:
{“gid”:“123”,
“resource_type”:“user”
},
“created_at”:“2019-08-27T19:19:18.879Z”,
“action”:“changed”,
“parent”:null,
“resource”:
{“gid”:“247”,
“resource_type”:“project”
}

1 Like

Hi @Seth,

Actually what you’re seeing is completely unrelated to this upcoming change; what you’ve run into is this change to webhook structure:

That change was announced many months ago and has been slowly rolled out, but yesterday was made live for good; see:

You’re right, though; looks like the documentation still needs to be updated. (@Joe_Trollo…)

2 Likes

Thanks Phil. Normally, my source of truth is the documentation - and it’s unfortunately wrong.

2 Likes

I have a PR open for this right now - it’s in my hands, @Phil_Seeman and @Seth.

@Phil_Seeman is right, this webhook change is for string IDs and not for the improvements @Joe_Trollo is mentioning above. Sorry for the delay on this, with our internal Roadmap Week it got put on the back burner :confused: but it’s high-priority for me at the moment. Expect updates soon!

1 Like

Hello all! I have some updates to share about pieces of this project that have now been shipped to the API.

First up, we’ve removed some noisy events from the API. There were a number of situations where we were emitting events for changes to properties that aren’t actually visible to users, or are side-effects of other events already being emitted. For example, there is a “last story time” value on tasks in our data model, but this is never exposed as a property of tasks in the web app or API. When users add tasks to projects, we add stories on the task describing those additions, but the task itself doesn’t change. The invisible internal field was updated, however, and so we were sending “task changed” events in addition to the “story added to task” and “task added to project” events. This (1) contributed to the “noisy” volume of events we send, and (2) was especially confusing when the task is added to a private project. In that case, the story and project are invisible to you, and so the “story added” and “task added” events wouldn’t fire, but the “task changed” event would.

As a result, adding or removing tasks to projects, moving tasks between columns, adding attachments on tasks, and a few other edge cases no longer emit “task changed” events. You will, however, still see the appropriate “task added to section/project” and “attachment added to task” events.

Secondly, we’ve added a field to event stream responses that tells you whether there are more events waiting on the server to be retrieved. This new field is called has_more and, if it’s true, your app should make another request right away to retrieve the additional events. Previously, there was no limit to the number of events returned in an event stream, but as we increase the amount of data in each event, this becomes more of a risk. To prevent issues in this area, we’ve decided to cap the number of events per event stream response to 100 (the same as the maximum number of events delivered in a single webhook body). Our metrics show that these responses were almost never over 100 events anyway, so there would be no present impact on apps already using event streams.

We’ll continue to provide updates as new features land in the API, and we are closing in on the final pieces for the full launch. Thank you all for your patience! As always, feel free to ask any questions you have and we’ll respond in this thread.

1 Like