Shortcut

Turn feedback into stories. Automatically create Shortcut stories when feedback is submitted. When a linked story's workflow state changes in Shortcut, the change appears in Quackback for your team to review.

Note: On Quackback Cloud, integrations are available on the Business and Enterprise plans. Self-hosted installs include every integration.

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 review: when a linked story's workflow state changes, the change appears in the integration's Sync history for a teammate to review

Prerequisites

• The Owner or Admin role in Quackback (or a custom role that can manage integrations)
• A Shortcut workspace
• A Shortcut API token (generated at Shortcut Settings > API Tokens)

Setup

1. Generate a Shortcut API token

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

Note: Shortcut uses API token authentication rather than OAuth. No application registration is required, on Cloud or self-hosted.

2. Connect your workspace

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

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

3. Select a team

Back in Quackback:

1. Choose the Shortcut team where stories should be created
2. Stories will be created in this team 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.

A second table maps the same workflow states to ticket statuses. It appears once status sync is on (step 5).

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:

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

7. Test

Settings save as you change them. Only the API token has a Save button.

1. 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 the author, the board, and a link back to the post in Quackback
• Story type: Feature
• Team: The selected Shortcut team

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. The change appears in Sync history for review. Quackback doesn't change the linked post's status on its own: update it yourself if the change applies

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, the delete dialog shows a checkbox for each linked story. A checked story is added to the integration's Sync history for review. Quackback doesn't archive it for you: open it in Shortcut and archive it there.

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 Integration 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. Click Disconnect on the Shortcut integration and confirm
3. Paste the new token into API Token, click Save, and choose the team again

Disconnect

To fully remove the integration:

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

Who is shown as the creator?

Quackback creates stories in Shortcut with the API token you connected, so Shortcut shows the owner of that token as the creator. To have stories created by a different account (for example, a shared bot account), generate a token as that account and reconnect.

Troubleshooting

Stories not being created

1. Check integration status: look for errors in settings
2. Verify team selection: ensure a Shortcut team is selected
3. Check the event: make sure Create story from new feedback is on
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

Token errors

Shortcut API tokens do not expire automatically but can be revoked. If the integration stops working:

1. Verify the token is still valid in Shortcut settings
2. Generate a new token if needed
3. Disconnect, then paste the new token into API Token and click Save

Related articles

• Linear: Linear issue integration
• Jira: Jira issue integration
• Integrations overview: All integrations