How to create a web hook to detect created tasks and updated tasks.

English Forum Developers & API
,
1

Hey, I have a question related to how to create a webhook to detect changes when a new task is created in the workspace. Or even if a task is changed.
I have a similar error described in this stack overflow thread. But in resume I’m using this JSON Body with establish Web Hook endpoint.

{
  "data": {
    "filters": [
      {
        "action": "added",
        "resource_type": "task"
      }
    ],
    "resource": "WORKSPACE_ID",
    "target": "URL"
  }
}

This is the response form the server

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

There is way to handle this approach?
I also have the following question if I want to create a webhook to detect changes in a task, should I create a webhook for each task? I think it would be crazy.

2

Hi @Luis_Pillaga,

I just discovered that it’s not well-documented in the API docs, but there are webhook scopes you need to be mindful of. Most importantly, you can only set a webhook on tasks at the project level, not higher than that. You can’t set it at the workspace level as you tried to do.

So no, you don’t have to create a webhook for each task - I agree, that would be crazy - but you do have to do it for each project.

@AndrewWong @John_Vu
As mentioned above, I never realized it till now, but the whole webhook-scope thing is hinted at but IMO not well-documented in the API docs. I think it would be great to have a whole “Webhook Scopes” section that explains it all.

2 Likes
3

Thank you very much for your response. I will continue with this approach.

1 Like
4

Hi @Luis_Pillaga,

TLDR; the reason why you are getting this error is because with workspace level webhooks, we do not return events for tasks hence why filtering for tasks does not work. In our docs → " Webhook events from tasks, subtasks, and stories won’t be propagated to these higher-level webhooks, so all changes on these resources are automatically filtered out." → in your scenario the resource gid you provided is of a workspace which is considered a higher-level webhook.

The suggestions as @Phil_Seeman mentioned, would be to establish webhooks at the project level to capture events about tasks within that project. The downside is you have to create a webhook for every project in your workspace.

EX:

{
  "data": {
    "resource": "<YOUR_PROJECT_GID>",
    "target": "<YOUR_TARGET_URL>",
    "filters": [
        {
            "action": "added",
            "resource_type": "task"
        }
    ]
  }
}
  • Repeat for all projects in your workspace → if you have over 10,000 projects in your domain that might be a problem since we have a 10,000 webhooks per token limit → you can get around this by creating a new access token and registering the next 10,000 webhooks on that token.

I agree with Phil, our webhooks documentation is lacking details about scope. I’ll bring up this suggestion about adding a “Webhook Scopes” section in our docs with my team.

As for filtering for webhooks at a high level, we do support webhooks at the team, portfolio, or workspace level but there are limitations:

  • Our higher-level webhooks do not propagate events that are lower level like in stories or tasks hence why you ran into the error message: "Webhooks for larger scoped resources must have at least one filter and all filters must be in our whitelist." when you provided a filter for tasks. This is because with this higher level webhook task events are not returned hence why the filter you provided is not valid.
  • You must provide filters → those filters should filter out events that would be returned at this level EX: If the gid you provided for resource is a workspace_gid then the next level is probably portfolios or projects. (We currently don’t document which events that these could be. Our API team is working on something that can help us document this)

So a working example would be:

{
  "data": {
    "resource": "<YOUR_WORKSPACE_GID>",
    "target": "<YOUR_TARGET_URL>",
    "filters": [
        {
            "action": "changed",
            "resource_type": "project"
        },
        {
            "action": "added",
            "resource_type": "project"
        }
    ]
  }
}

Here’s another way to think about this. So let’s say we have the following levels:

level 1 - workspace
level 2 - portfolios
level 3 - projects
level 4 - tasks
level 5 - stories

If you think of a sliding window that can only capture events at two levels you can understand how this works. For example, let’s say for resource gid you provide a gid at level 2 - portfolios → this means that the events that would be returned to you for this webhook could be at level 2 or level 3. Knowing this, you can provide filters for events on portfolios itself or projects and not tasks since the window is limited to 2 levels.

NOTE: I am using a sliding window of 2 as an example. I am not sure what the actual range is with all our webhooks. I just wanted to give an example that would help explain how to think about this filtering. Hence why we say “In addition, the set of event filters that can be placed on a team-level or workspace-level webhook is more limited than filters for webhooks that are created on lower-level resource” … " * Webhook events from tasks, subtasks, and stories won’t be propagated to these higher-level webhooks, so all changes on these resources are automatically filtered out."

4 Likes
5

This topic was automatically closed 7 days after the last reply. New replies are no longer allowed.