Skip to main content

Shortcut to Harvestr Status Synchronization (via Zapier)

Sync Shortcut Story Status to Harvestr Discovery Status with Zapier

Written by Marina Salmon
Updated over a week ago

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

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 you have access to this feature with your plan.

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 is not required.

In Zapier

You need:

  • A Zapier account

  • Access to Webhooks by Zapier

Step 1 — Create a Zap and catch the webhook

In Zapier:

  1. Click Create Zap

  2. Choose:

  • App: Webhooks by Zapier

  • Event: Catch Hook

Zapier will generate 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. You need to filter so the Zap only runs when a Story's workflow state changes.

Add a step: Filter by Zapier.

Use the following 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) corresponds to the new workflow state. You will use its References Name field later in Step 8 to map it to a Harvestr status.

Optional: filter specific state transitions

You can add extra conditions to react only to certain transitions. For example:

  • 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 (e.g., done, started, unstarted) if you prefer to match on state categories rather than exact names.

Step 5 — Retrieve full Story details

The webhook payload does not 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 step: Shortcut app → Search Stories

Connect your Shortcut account to Zapier with the API key.

Add the Actions ID parameter from the Webhook step to the Query field.

This value corresponds to the ID of the Story that was updated.

This 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

Use 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 to see if the Discovery ID is extracted correctly from the Harvestr URL.

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 API endpoint from our docs to list your discovery states:

  • click Authorize and your token

  • click Execute and keep the corresponding state IDs available 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 (Step 1). This is the name of the new workflow state (e.g., "Completed", "In Progress").

Lookup table setup

In the left column, put your Shortcut status names. Alternatively, you can also map the 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.

Example:

Shortcut status

Harvestr discoveryStateId

Planned

abc

In progress

xyz

Done

123

The output of this step will be the correct Harvestr discoveryStateId.

Step 9 — Update the Discovery in Harvestr

Add a final step:

  • Webhooks by Zapier

  • Action event: Custom Request

Configure it like this:

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 the following 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 item has a valid Harvestr URL

  • the Discovery ID extraction works correctly

  • the lookup table contains the correct Harvestr discovery state IDs

  • your Harvestr API token has the right permissions

The wrong status is applied

Review the lookup table and confirm that each Shortcut status name is mapped to the correct Harvestr discoveryStateId.

Did this answer your question?