Skip to main content

Sync Shortcut statuses to Harvestr via Zapier

Sync Shortcut Story Status to Harvestr Discovery Status with Zapier

Written by Marina Salmon

This guide explains how to automatically update the status of a Discovery when the workflow state of a linked Shortcut Story changes.

There is no native Shortcut integration. This recipe runs through Zapier and the Harvestr API, so a Zapier account is required.

If you use Jira or Linear, status sync is built in — no Zapier needed.

What you need

To enable the synchronization, you need to link Shortcut Stories to Harvestr Discoveries and configure access to both systems.

In Shortcut

You need:

  • Access to workspace settings

  • Permission to create webhooks

  • A Shortcut API token (used by Zapier to retrieve Story details)

Each Story you want to sync must contain the URL of the corresponding Harvestr Discovery.

Recommended method: paste the Discovery URL into the Story's External Links field.

You can also use Shortcut's Custom Fields if your plan includes them.

In Harvestr

You need:

  • A read_discovery API token to list Discovery states

  • A write_discovery API token to update Discovery statuses

Optionally, you may create a field to store the Shortcut Story URL on the Discovery for visibility, but this isn't required.

In Zapier

You need:

  • A Zapier account

  • Access to Webhooks by Zapier

Step 1 — Create a Zap and catch the webhook

In Zapier, create a new Zap and choose:

  • App: Webhooks by Zapier

  • Event: Catch Hook

Zapier generates a webhook URL. Copy it.

Step 2 — Create a webhook in Shortcut

In Shortcut:

  1. Go to Settings → Integrations → Webhooks

  2. Create a new webhook

  3. Paste the Zapier URL and click Add New Webhook

Step 3 — Trigger a test event

Update a Story in Shortcut (for example, change its workflow state).

In Zapier, click Test trigger. You should receive webhook data from Shortcut.

Step 4 — Filter relevant events

Shortcut webhooks fire for many types of changes. Filter so the Zap only runs when a Story's workflow state changes.

Add a Filter by Zapier step with these conditions:

  • Actions Action exactly matches update

  • Actions Entity Type exactly matches story

  • References Entity Type exactly matches workflow-state,workflow-state

When a Story changes workflow state, Shortcut includes two references in the payload: the new state and the previous state. Both have Entity Type = workflow-state, which is why the value appears twice, comma-separated.

The first reference (References 1) is the new workflow state. You'll use its References Name field in Step 8 to map it to a Harvestr status.

Optional: filter specific state transitions

Add extra conditions to react only to certain transitions:

  • Only when moved to a specific state: add a condition where References 1 References Name exactly matches the target state name (e.g. Completed)

  • Only when moved from a specific state: use References 2 References Name instead

You can also filter on References Type (done, started, unstarted) to match on state categories rather than exact names.

Step 5 — Retrieve full Story details

The webhook payload doesn't contain all Story data, including external links.

First, create an API token in Shortcut: Settings → API Tokens → Generate token. It can be read-only.

In Zapier, add a Shortcut → Search Stories step and connect your Shortcut account with that API key.

Add the Actions ID parameter from the webhook step to the Query field. This is the ID of the Story that was updated.

The step returns full Story details, including external links.

Step 6 — Ensure the Story contains a Harvestr URL

Add another Filter step to continue only if External Links contain app.harvestr.io.

Step 7 — Extract the Discovery ID from the Harvestr URL

Add Formatter by Zapier → Text → Extract Pattern with this regex:

https:\/\/app\.harvestr\.io\/components\/[^\s"]*(?:\?v=|\/)([A-Za-z0-9_-]+)

This extracts the Discovery ID from any supported Harvestr URL format. Test it to confirm the ID comes out correctly.

Step 8 — Map Shortcut workflow state to a Harvestr state ID

First, get your Harvestr discovery state IDs

Go to your Harvestr API settings and create a read_discovery API token.

Use the list discovery states endpoint to list your states:

  • click Authorize and paste your token

  • click Execute and keep the state IDs handy for the next steps

In Zapier

Add a step:

  • Formatter by Zapier

  • Action event: Utilities

  • Transform: Lookup Table

  • Lookup key: select References 1 References Name from the webhook step. This is the name of the new workflow state.

Lookup table setup

In the left column, put your Shortcut status names. You can alternatively map Shortcut status IDs by retrieving them via the Shortcut API.

In the right column, put the corresponding Harvestr discovery state IDs retrieved from the API.

Shortcut status

Harvestr discoveryStateId

Planned

abc

In progress

xyz

Done

123

The output of this step is the correct Harvestr discoveryStateId.

Step 9 — Update the Discovery in Harvestr

Add a final step:

  • Webhooks by Zapier

  • Action event: Custom Request

Configure it as follows.

Method

PATCH

URL

https://rest.harvestr.io/v1/discovery/<DISCOVERY_ID>

Replace <DISCOVERY_ID> with the output field from Step 7.

Data

Use raw JSON:

{
  "discoveryStateId": "<MAPPED_DISCOVERY_STATE_ID>"
}

Replace <MAPPED_DISCOVERY_STATE_ID> with the output of the lookup table from Step 8.

Headers

  1. Go to Settings → Integrations → API

  2. Create a new write_discovery token

  3. In Zapier, add these headers:

Content-Type

application/json

X-Harvestr-Private-App-Token

your write_discovery token

Step 10 — Publish and test

  1. Move a Story to a new workflow state in Shortcut

  2. Check the Zap run

  3. Confirm the Discovery status updates in Harvestr

Troubleshooting

The Zap runs but nothing updates in Harvestr

Check that:

  • the Shortcut Story has a valid Harvestr URL in its External Links

  • the Discovery ID extraction in Step 7 works correctly

  • the lookup table contains the correct Harvestr discovery state IDs

  • your Harvestr API token carries the write_discovery scope

The wrong status is applied

Review the lookup table and confirm each Shortcut status name maps to the correct Harvestr discoveryStateId.

Did this answer your question?