QuackbackQuackback
Navigation

Shortcut

Turn feedback into stories. Automatically create Shortcut stories when feedback is submitted, and keep statuses synchronized between Quackback and Shortcut. When a story's workflow state changes in Shortcut, the linked feedback post updates too.

Overview

The Shortcut integration enables:

  • Create Shortcut stories from feedback posts -- automatically create a story when new feedback is submitted
  • Link posts to stories -- link feedback posts to Shortcut stories for traceability
  • Status sync -- keep feedback post status and Shortcut story workflow state in sync via inbound webhooks

Prerequisites

Setup

1. Generate a Shortcut API Token

  1. Go to Shortcut Settings > API Tokens
  2. Generate a new API token
  3. Copy the token

Shortcut uses API token authentication rather than OAuth. No application registration is required.

2. Connect Your Workspace

  1. Go to Admin → Settings → Integrations → Shortcut
  2. Enter your API Token
  3. Click Save

Quackback validates the token by checking it against the Shortcut API and automatically detects your workspace name.

3. Select a Project

Back in Quackback:

  1. Choose the Shortcut project where stories should be created
  2. Stories will be created in this project when new feedback is submitted

4. Configure Status Mappings

Map Shortcut workflow states to Quackback statuses:

  1. Go to the Shortcut integration settings
  2. Configure status mappings between Shortcut workflow state names and Quackback statuses
  3. Each Shortcut workflow state can be mapped to a corresponding Quackback status, or set to ignore

Shortcut uses workflow state IDs internally. Quackback resolves the ID to a state name from the webhook payload itself before looking up your mapping, so renaming or adding workflow states in Shortcut doesn't break the sync.

5. Set Up the Inbound Webhook

Status sync needs a webhook in Shortcut so story changes reach Quackback:

  1. In Quackback, enable Status sync in the Shortcut integration settings
  2. Copy the Webhook URL and Signing secret shown below the toggle
  3. In Shortcut, go to Settings → Integrations → Webhooks and add a new outgoing webhook
  4. Paste the webhook URL as the payload URL and the signing secret as the secret

Quackback verifies each delivery against the signing secret and rejects requests that don't match.

6. Configure Events

Choose which events trigger Shortcut actions:

EventAction
New postCreate a Shortcut story with the feedback details

The Shortcut integration currently creates stories only for post.created events. Status changes and comments are handled through the status sync mechanism rather than creating new stories.

7. Save and Test

  1. Click Save
  2. Submit test feedback to verify a story is created in Shortcut

Story Format

When a new feedback post triggers story creation, the Shortcut story includes:

  • Name: The feedback post title (truncated to 512 characters if needed)
  • Description (Markdown): The post content, followed by metadata including the author, board, vote count, and a link back to the post in Quackback
  • Story type: Feature
  • Project: The selected Shortcut project

Status Sync

When status sync is configured, Quackback receives webhook events from Shortcut. When a linked story's workflow state changes:

  1. Shortcut sends a webhook event to Quackback
  2. Quackback looks for story update actions with workflow_state_id changes
  3. The new workflow state ID is resolved to a state name using the workflow-state references included in the payload
  4. If a status mapping exists for that state name, the linked feedback post's status is updated

The webhook signature is verified using HMAC-SHA256 via the Payload-Signature header, using the signing secret from your integration settings.

On post delete

When you delete a feedback post with a linked Shortcut story, you can archive the story at the same time. The delete dialog shows a checkbox for each linked story.

To pre-check this by default, enable the On post delete toggle in the Shortcut integration settings. You can always override the default per-delete.

Manage the integration

Pause

Temporarily stop the integration:

  1. Go to Admin → Settings → Integrations → Shortcut
  2. Toggle Enabled off
  3. Story creation and status sync pause, but the connection remains

Reconnect

If you see connection errors:

  1. Generate a new API token in Shortcut
  2. Update the token in Admin → Settings → Integrations → Shortcut

Disconnect

To fully remove the integration:

  1. Go to Admin → Settings → Integrations → Shortcut
  2. Click Disconnect
  3. Confirm the action

Troubleshooting

Stories Not Being Created

  1. Check integration status -- look for errors in settings
  2. Verify project selection -- ensure a Shortcut project is selected
  3. Check event mappings -- confirm post.created is mapped
  4. Validate API token -- ensure the token has not been revoked in Shortcut

Status Sync Not Working

  1. Check status mappings -- ensure Shortcut workflow states are mapped to Quackback statuses
  2. Check the webhook -- confirm the webhook exists in Shortcut and its payload URL matches the webhook URL in your integration settings
  3. Check the secret -- the secret in Shortcut must match the signing secret shown in Quackback; deliveries with a wrong or missing signature are rejected

"Authentication Failed" Error

Shortcut API tokens do not expire automatically but can be revoked. If you see this error:

  1. Verify the token is still valid in Shortcut settings
  2. Generate a new token if needed
  3. Update the token in Quackback

Next Steps