Skip to main content

​
Prerequisites

Before continuing, you should have already completed the following for this connector:
1

Configure the Connector

Enable the connector and set up its connector profile in your project. See Managing Connectors.

Connector Profile

Asana - Personal Access Token

Connector Profile

Asana - OAuth 2.0
2

Link an Account

Connect an account using StackOne Hub or Auth Link.

Link Account

Asana - Personal Access Token

Link Account

Asana - OAuth 2.0

​
Subscribe via the StackOne dashboard

This connector uses Programmatic Webhooks. When you connect an Asana account, StackOne automatically creates the webhook subscriptions (via POST /webhooks) pointing at your StackOne callback URL. Because Asana does not propagate task, story, or section events to workspace-level webhooks, the connector registers a hybrid set: one workspace-scoped subscription for project creation, plus one project-scoped subscription for each Project ID you configure (for task, story, and section events). Each subscription carries a fixed filter set for its scope; StackOne then emits downstream only the events you have enabled on the connection.

1

Check scopes

Ensure the connected application has webhooks:read, webhooks:write, and webhooks:delete OAuth scopes enabled. Without these, subscription creation will fail.

2

Select event subscriptions in the dashboard

In the StackOne dashboard, open the Asana connector profile and enable the webhook events you want delivered downstream. See the Available Webhook Events section below for the full list.

3

Registration on subscribe

On connect, StackOne creates the subscriptions on your behalf. The workspace subscription is registered against your configured Workspace ID (fixed filter: project added). A separate project subscription is registered against each configured Project ID (fixed filters: task added/changed/removed/deleted, story added/removed, section added/changed).

  • StackOne registers webhooks with a fixed filter set per scope; only the events you enable on the connection are emitted downstream.
  • Task, story, and section events require at least one Project ID to be configured — they are not delivered by the workspace-level webhook.
  • Asana sends an in-flight X-Hook-Secret handshake to StackOne’s callback URL during creation — this is handled automatically.
  • Asana delivers events as a JSON body with an events array. Multiple changes can be batched in a single delivery.
4

Heartbeat verification

Asana sends an empty-events heartbeat POST to the webhook URL every 8 hours. StackOne responds with 200 OK automatically to prevent Asana from disabling the subscription.

5

Unsubscribe

Changing your event selection re-registers the StackOne-managed subscription. Disconnecting the account deletes it, stopping deliveries.

​
Available Webhook Events

The following Asana events can be enabled. All events are filtered by resource_type and action via Asana’s webhook filters mechanism.

1

Task events

Events fired when tasks are created, modified, or removed.

  • Task Added (task.added) — Fired when a task is added to a project or workspace
  • Task Changed (task.changed) — Fired when a task’s properties are modified
  • Task Removed (task.removed) — Fired when a task is removed from a project
  • Task Deleted (task.deleted) — Fired when a task is permanently deleted
2

Project events

Fired at the workspace level when a project is created. Note: Asana delivers only project creation to workspace-level webhooks — project modifications and deletions are not available via webhooks.

  • Project Added (project.added) — Fired when a project is added to a team or workspace
3

Story events

Events fired when comments or activity stories are added to or removed from tasks.

  • Story Added (story.added) — Fired when a comment or activity story is added to a task
  • Story Removed (story.removed) — Fired when a story is removed from a task
4

Section events

Events fired when sections within a project are added or modified.

  • Section Added (section.added) — Fired when a section is added to a project
  • Section Changed (section.changed) — Fired when a section’s name or properties are modified

​
Delivery format

Details of how Asana delivers events to StackOne.

1

JSON payloads

Asana delivers each webhook as an HTTP POST with a JSON body containing an events array. Each array element includes action (added, changed, removed, deleted), resource (with gid and resource_type), parent, created_at, and user. Multiple changes may be batched in one delivery.

2

Signature verification

Asana includes an X-Hook-Signature header — a SHA256 HMAC signature computed over the request body using the X-Hook-Secret established during the creation handshake.

​
Verify

Your Connector should now be able to receive and process events. Try triggering an event and you should see an Event appear in the Connector logs.