# Aha! Roadmaps
URL: https://docs.clearly-ai.com/docs/integrations/issue-trackers/aha
Description: Connect Clearly AI to Aha! Roadmaps.
Connect Aha! Roadmaps so Clearly AI can read ideas and roadmap features as Project sources, post comments, and receive Aha! activity events for Workflows.

Clearly AI acts as the Aha! user whose API key you configure. For example, if the key was generated by `alex@example.com`, comments created by Clearly AI appear as Alex.

[Image: Aha! comment authored by the credential owner]

<Note>
  For shared or production use, ask an Aha! administrator to create a dedicated service account, such as **Clearly AI bot**, and generate the API key from that account. Aha! API keys inherit the permissions of the user that created them, so this keeps Clearly AI activity separate from individual employee accounts.
</Note>

## Create the Aha! API key [#create-the-aha-api-key]

1. In Aha!, click your user avatar and open **Settings → Personal**.
2. Select **Developer** in the left sidebar.
3. Click **Generate API key**.
4. Enter a descriptive name, such as `Clearly AI`, and click **Generate**.
5. Copy the key. Aha! shows it only once.

[Image: Aha! Developer settings with Generate API key]

[Image: Aha! API key created]

## Connect Aha! in Clearly AI [#connect-aha-in-clearly-ai]

1. In Clearly AI, open **Organization settings**, select **Integrations**, then click **Set up** on the Aha! card.
2. In **Account subdomain**, enter the hostname before `.aha.io`. For `https://acme.aha.io`, enter `acme`.
3. Under **Authentication**, in **Shared API Token**, paste the Aha! API key.
4. Check **I understand** under the shared-credential notice, then click **Add workspace credential**. Clearly AI tests the credential and enables the integration only when the test passes.

The test checks that Clearly AI can authenticate against `https://{subdomain}.aha.io`. If it fails, check the subdomain, the API key, and the account's access.

## Configure Aha! activity webhooks for Workflows [#configure-aha-activity-webhooks-for-workflows]

Configure an activity webhook if you want Aha! events, such as idea or feature changes, to trigger Clearly AI Workflows.

<Note>
  You need Aha! account administrator privileges with customization access to create an account-level activity webhook, or workspace owner access for a single workspace.
</Note>

### Generate the Clearly AI webhook URL [#generate-the-clearly-ai-webhook-url]

Aha! activity webhooks cannot send custom request headers, so Clearly AI embeds the webhook secret directly in the URL as a `whs` query parameter. Treat the full webhook URL as a secret.

1. In Clearly AI, open **Organization settings**, select **Integrations**, click **Configure** on the Aha! card, open the **Webhooks** tab, and click **Edit webhook**.
2. Click **Generate new secret** next to **Secret**.
3. Click **Apply and Test**.
4. Click **Edit webhook** again and copy the **Webhook URL**. The displayed URL already includes the secret as `?whs=...`.

Use the full generated URL from Clearly AI when you configure Aha!. Do not remove the `?whs=...` query parameter.

### Create the activity webhook in Aha! [#create-the-activity-webhook-in-aha]

In Aha!, open **Settings → Account → Integrations** for an account-level webhook, or **Settings → Workspace → Integrations** for a single workspace.

1. Select **Activity webhook** from the list of available integrations.
2. In **Hook URL**, paste the Clearly AI webhook URL, including the `?whs=...` portion.
3. Add the record types that should trigger Workflows:
   * **Idea** for idea events.
   * **Feature** for roadmap feature events.
   * Optionally **Comment** to also receive comments posted on ideas and features.
4. Enable **Deliver immediately** if events should bypass the default five-minute Aha! delay.
5. Check **Enable** and save the integration.

[Image: Aha! activity webhook configuration]

Clearly AI only acts on idea and feature audit events. Other record types are accepted by the endpoint but ignored. To confirm the setup, return to the Aha! integration in Clearly AI and use **Validate your request configuration**. A correct setup returns `200 OK`. After validation succeeds, Aha! activity that matches your selected record types can trigger Clearly AI Workflows.

## Custom fields on a feature status change [#custom-fields-on-a-feature-status-change]

A later workflow step can use a custom field from the Aha! feature that changed. On the **Aha! Feature status changed** trigger, open **Custom field lookups** and enter that field's key or its display name, such as `Assigned Pod`. Save the workflow.

Each lookup becomes its own output on the trigger. In a later step, type `@` and insert it. The output is empty when the feature does not include that field, or when the field has no value.

The trigger checks the field key first. When no key matches, it checks the display name and ignores case. If Aha! stores the value as structured data instead of text, the step stops and reports that the lookup cannot convert the value to text. If **Custom field lookups** is set and Clearly AI cannot load the feature, the trigger stops and the workflow does not continue.

## FAQs [#faqs]

<Accordions>
  <Accordion title="Why does the connection test fail?">
    Confirm the subdomain is the hostname before `.aha.io` with no protocol or `.aha.io` suffix, the API key is active, and the user that created the key can sign in to that Aha! account.
  </Accordion>

  <Accordion title="Why do comments appear under the wrong user?">
    Clearly AI comments as the Aha! user that generated the API key. Use a dedicated service account if you need consistent attribution.
  </Accordion>

  <Accordion title="Why does webhook validation fail?">
    Confirm the activity webhook is enabled, uses the current Clearly AI webhook URL with the `?whs=...` query parameter intact, and is configured for at least the Idea or Feature record type. Aha! cannot add a custom header, so the secret must be in the URL.
  </Accordion>

  <Accordion title="Why doesn't the Workflow run after an Aha! update?">
    Confirm the activity webhook covers the relevant record type, the audit event was actually delivered (default delay is five minutes unless **Deliver immediately** is enabled), and the Workflow is enabled in Clearly AI.
  </Accordion>

  <Accordion title="Why is an Aha! custom field empty in a workflow?">
    The **Aha! Feature status changed** output is empty when that field is not set on the feature. Check the value in Aha!, then check that **Custom field lookups** uses the field key or display name.
  </Accordion>
</Accordions>

## Related [#related]

* [Integrations](https://docs.clearly-ai.com/docs/integrations)
* [Workflows](https://docs.clearly-ai.com/docs/workflows)