Hi all, we have a new update to share. Our above plan is still accurate, and we’re aiming to let developers start migrating in early November. Notably, though, the plan is missing one crucial component: webhooks.
Our deprecations framework is built into our framework for handling API requests. Webhooks, however, originate from within Asana’s API and are not made in response to any request. Client don’t send any headers, and so there’s no way to use those headers to define behavior. Because of this, we’re adding new settings to webhooks and OAuth apps/PATs directly. Here’s how these settings will work:
To test out string IDs in a particular webhook, you will be able to set a boolean flag on the webhook itself, either when it’s created or in a follow-up request to PUT /webhooks/<webhook-id>. When this flag is set to true, the webhook bodies will be sent with string IDs. When it’s false, it falls back to the settings on the OAuth app/PAT.
Once you’re confident that your app can handle webhooks with string IDs, you can toggle an app-level option to decide the global behavior for all webhooks (so that you don’t need to manually update each and every one). This option will have three states: “default,” “disabled,” and “enabled,” which roughly correspond to “not setting any header,” “setting an Asana-Disable header” and “setting an Asana-Enable header” respectively.
To clarify the various configurations, here’s a table that enumerates them all:
| App setting | Webhook setting | Behavior |
|---|---|---|
| Default | False | numeric IDs before activation, string IDs after activation |
| Default | True | string IDs |
| Disabled | False | numeric IDs |
| Disabled | True | string IDs |
| Enabled | False | string IDs |
| Enabled | True | string IDs |
Now, the current webhook event structures are kinda weird and don’t fit with the rest of the API. In particular, there are no id fields that we could replace with gid. Instead, they look like this:
{
"resource": 1337,
"parent": null,
"created_at": "2013-08-21T18:20:37.972Z",
"user": 1123,
"action": "changed",
"type": "task"
}
We’re going to take advantage of this deprecation to make them match the rest of the API. When string IDs are enabled, these events will match our events API and look like this:
{
"resource": {
"gid": "1337",
"resource_type": "task"
},
"parent": null,
"created_at": "2013-08-21T18:20:37.972Z",
"user": {
"gid": "1123",
"resource_type": "user"
},
"action": "changed"
}
While seemingly benign, this structural change actually opens the door for a massive improvement to our API that I’ll talk about in a later announcement, so stay tuned! And as always, please ask any questions you have in this thread so that we can ensure this process is clear for all developers. Thank you for your patience!