Shortcut integration

Create Shortcut Stories from Compfeed components, and keep Compfeed phases and Shortcut workflow states in sync in both directions.

Before you start

A Compfeed organization on the Org plan.
An organization Owner, to connect Shortcut and add the webhook.
A team admin or editor for each team, to choose its Shortcut team and workflow and map its phases.
A Shortcut member (not an Observer) to create an API token with read and write access.

Set up the integration

Connect Shortcut

Organization Owner

In Shortcut, open Settings > Your Account > API Tokens and generate a token with read and write access.
In Compfeed, open Settings > Connections, choose Shortcut and paste the token.

One Compfeed organization connects to one Shortcut workspace.

Get updates from Shortcut

Organization Owner

In Settings > Connections > Shortcut, generate the webhook secret and copy it straight away.
Copy the Payload URL shown with it.
In Shortcut, open Settings > Integrations > Webhooks, add a webhook with that Payload URL and secret, and save.

⚠️

The webhook secret is shown once. Copy it before you close the dialog.

Without this step Compfeed still creates and moves Stories, but changes made in Shortcut do not come back.

Set up each team

Team admin

Open Settings > Teams, choose the team, and pick the Shortcut Workspace (the Shortcut team its Stories go to) and Workflow.

Map phases to workflow states

Team admin or editor

In the process editor, open a phase’s Shortcut mapping and choose a workflow state and a direction:

Two-way: changes go both ways.
Outbound only: Compfeed moves the Story; changes in Shortcut are ignored.
Inbound only: Shortcut moves the component; Compfeed does not move the Story.

A phase without a mapping stays out of the sync.

Create a Story

On a component, open its menu and choose Create story. The Story lands in the team’s Shortcut team and workflow, with a link back to the component.

What syncs

You do	Compfeed	Shortcut
Create story on a component	Component linked to the Story	Story created in the team’s Shortcut team and workflow, with a link to the component
Move a component into a phase mapped two-way or outbound only	Phase changes	Story moves to the mapped workflow state
Move a Story into a state mapped two-way or inbound only	Component moves to the mapped phase; activity entry; live update	State changes
Archive or delete the Story	Link removed	Story archived or deleted

Your own token

Everyone can connect their own Shortcut token in Settings > Connections, so actions in Shortcut are made as them. Without one, Compfeed uses a team admin’s or the Owner’s token.

Troubleshooting

Token rejected: the token is read-only or belongs to an Observer. Generate a read-write token as a member.
Shortcut is not connected: the Owner has not connected Shortcut yet, or the token was removed.
Changes in Shortcut do not show in Compfeed: check the webhook’s Payload URL and secret, and check that the phase is mapped two-way or inbound only.
Story lands in the wrong team or state: check the team’s Workspace and Workflow, and its phase mappings.
Token stopped working: connect a new token in Settings > Connections.

Disconnect

Disconnecting in Settings > Connections removes your token from Compfeed. Stories already created stay in Shortcut. To stop updates from Shortcut, delete the webhook in Shortcut.

Security

Tokens and the webhook secret are encrypted at rest.
Every webhook is checked against your secret; events with a missing or wrong signature are rejected.
Events from another Shortcut workspace are ignored.
Only members of your organization can use its Shortcut connection.

Example Privacy Policy