Webhooks — Shortcut Help Center

Overview

If you’re building a custom integration with Shortcut and need to register webhooks programmatically, you can use the REST API to manage webhooks instead of configuring them manually in the UI.

For full API documentation, see the Webhooks API Reference.

Authentication

All webhook API routes require a Shortcut token provided via the Shortcut-Token header. Users of your integration need to provide a Shortcut API token generated by a non-Observer member of their workspace.

Create a Webhook Integration

Request

POST https://api.app.shortcut.com/api/v3/integrations/webhook
Shortcut-Token: your-token
Content-Type: application/json

{"webhook_url": "https://example.com/", "secret": "a-secret"}

Available Fields

Field	Required	Description
`webhook_url`	Yes	The URL where webhook payloads will be sent
`secret`	No	A string used to verify payloads via HMAC signature in the `Payload-Signature` header

Response

{
  "entity_type": "integration",
  "webhook_url": "https://example.com/",
  "disabled": false,
  "type": "generic",
  "creator_id": "5a7e1b9a-edb2-4c48-b31f-462864df62ca",
  "updated_at": "2025-02-11T12:36:31Z",
  "id": 500107362,
  "has_secret": true,
  "created_at": "2025-02-11T12:36:31Z"
}

The id field is used for subsequent operations.

Get a Webhook Integration

Request

GET https://api.app.shortcut.com/api/v3/integrations/webhook/500107362
Shortcut-Token: your-token

Response

{
  "entity_type": "integration",
  "webhook_url": "https://example.com/",
  "disabled": false,
  "type": "generic",
  "creator_id": "5a7e1b9a-edb2-4c48-b31f-462864df62ca",
  "updated_at": "2025-02-11T12:36:31Z",
  "id": 500107362,
  "has_secret": true,
  "created_at": "2025-02-11T12:36:31Z"
}

Delete a Webhook Integration

Request

DELETE https://api.app.shortcut.com/api/v3/integrations/webhook/500107362
Shortcut-Token: your-token

Send Shortcut Activity to Other Apps

Outgoing webhooks can send Shortcut events to Zapier, enabling you to connect Shortcut activity to any of the 1,500+ Zapier apps. This guide covers setting up the webhook connection between Shortcut and Zapier.

How to Enable Shortcut Webhooks

Navigate to Settings > Integrations > Webhooks
Click + Add New Webhook
You’ll be asked to provide a Payload URL (get this from Zapier first)

The secret is not needed for this integration.

Getting the Payload URL from Zapier

The Payload URL is where Shortcut sends event data. To get it from Zapier:

Login to your Zapier account
Click Create Zap from your Dashboard
Search for Webhooks by Zapier (this is a premium app)
Under Choose Trigger Event, select Catch Hook
Click Continue
Copy the generated Payload URL
Return to Shortcut, paste the Payload URL, and click Add New Webhook
Switch back to Zapier and click Continue

Test the Connection

To verify Zapier is receiving Shortcut events:

In Zapier, click Test & Review to start listening for events
Go to Shortcut and trigger an event (e.g., move a Story, add a label)
Return to Zapier to confirm the event was captured

Example Events to Trigger

Move a Story to “Ready for QA”
Move an Epic to “Started” state
Add or remove a Label from a Story
Set a deadline on a Story
Create a new Story

Connect to Your Favorite App

After confirming Zapier captured the Shortcut event, select what happens when the event occurs by choosing your destination app and following its setup instructions.

Zapier Template Ideas

GitHub: Create issues from Shortcut Stories
Slack: Post notifications when Stories change state
Zendesk: Create tickets from Shortcut activity
Custom Webhooks: Send data to any endpoint