> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Asana Webhook Setup Guide

> Configure Asana to deliver events to StackOne.

## Prerequisites

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

<Steps>
  <Step title="Configure the Connector">
    Enable the connector and set up its connector profile in your project. See <a href="/guides/explore-connectors">Managing Connectors</a>.

    <Columns cols={2}>
      <Card title="Connector Profile" href="/connectors/asana/guides/connector-profile/personal-access-token" icon="https://stackone-logos.com/api/asana/filled/png" horizontal>
        Asana - Personal Access Token
      </Card>

      <Card title="Connector Profile" href="/connectors/asana/guides/connector-profile/oauth-2-0" icon="https://stackone-logos.com/api/asana/filled/png" horizontal>
        Asana - OAuth 2.0
      </Card>
    </Columns>
  </Step>

  <Step title="Link an Account">
    Connect an account using <a href="/guides/embedding-stackone-hub">StackOne Hub</a> or <a href="/guides/auth-link">Auth Link</a>.

    <Columns cols={2}>
      <Card title="Link Account" href="/connectors/asana/guides/link-account/personal-access-token" icon="https://stackone-logos.com/api/asana/filled/png" horizontal>
        Asana - Personal Access Token
      </Card>

      <Card title="Link Account" href="/connectors/asana/guides/link-account/oauth-2-0" icon="https://stackone-logos.com/api/asana/filled/png" horizontal>
        Asana - OAuth 2.0
      </Card>
    </Columns>
  </Step>
</Steps>

<section data-guide-section data-guide-scopes="">
  <h2>Subscribe via the StackOne dashboard</h2>

  <p>This connector uses <strong>Programmatic Webhooks</strong>. 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 <strong>hybrid</strong> set: one <strong>workspace-scoped</strong> subscription for project creation, plus one <strong>project-scoped</strong> 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.</p>

  <Steps>
    <Step title="Check scopes">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Ensure the connected application has `webhooks:read`, `webhooks:write`, and `webhooks:delete` OAuth scopes enabled. Without these, subscription creation will fail.</p>
      </div>
    </Step>

    <Step title="Select event subscriptions in the dashboard">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>In the StackOne dashboard, open the Asana connector profile and enable the webhook events you want delivered downstream. See the <strong>Available Webhook Events</strong> section below for the full list.</p>
      </div>
    </Step>

    <Step title="Registration on subscribe">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>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).</p>

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

    <Step title="Heartbeat verification">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>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.</p>
      </div>
    </Step>

    <Step title="Unsubscribe">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Changing your event selection re-registers the StackOne-managed subscription. Disconnecting the account deletes it, stopping deliveries.</p>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Available Webhook Events</h2>

  <p>The following Asana events can be enabled. All events are filtered by resource\_type and action via Asana's webhook filters mechanism.</p>

  <Steps>
    <Step title="Task events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events fired when tasks are created, modified, or removed.</p>

        <ul>
          <li><strong>Task Added</strong> (`task.added`) — Fired when a task is added to a project or workspace</li>
          <li><strong>Task Changed</strong> (`task.changed`) — Fired when a task's properties are modified</li>
          <li><strong>Task Removed</strong> (`task.removed`) — Fired when a task is removed from a project</li>
          <li><strong>Task Deleted</strong> (`task.deleted`) — Fired when a task is permanently deleted</li>
        </ul>
      </div>
    </Step>

    <Step title="Project events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>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.</p>

        <ul>
          <li><strong>Project Added</strong> (`project.added`) — Fired when a project is added to a team or workspace</li>
        </ul>
      </div>
    </Step>

    <Step title="Story events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events fired when comments or activity stories are added to or removed from tasks.</p>

        <ul>
          <li><strong>Story Added</strong> (`story.added`) — Fired when a comment or activity story is added to a task</li>
          <li><strong>Story Removed</strong> (`story.removed`) — Fired when a story is removed from a task</li>
        </ul>
      </div>
    </Step>

    <Step title="Section events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events fired when sections within a project are added or modified.</p>

        <ul>
          <li><strong>Section Added</strong> (`section.added`) — Fired when a section is added to a project</li>
          <li><strong>Section Changed</strong> (`section.changed`) — Fired when a section's name or properties are modified</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Delivery format</h2>

  <p>Details of how Asana delivers events to StackOne.</p>

  <Steps>
    <Step title="JSON payloads">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>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.</p>
      </div>
    </Step>

    <Step title="Signature verification">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>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.</p>
      </div>
    </Step>
  </Steps>
</section>

## 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.