# Webhooks

Programmatically register and manage Shortcut webhooks using the REST API for custom integrations.

## 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](https://developer.shortcut.com/api/webhook/v1#Shortcut-Outgoing-Webhooks).

## Authentication

All webhook API routes require a [Shortcut token](https://developer.shortcut.com/api/rest/v3#Authentication) 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

```http
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

```json
{
  "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

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

### Response

```json
{
  "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

```http
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](https://zapier.com/apps). This guide covers setting up the webhook connection between Shortcut and Zapier.

### How to Enable Shortcut Webhooks

1. Navigate to **Settings > Integrations > Webhooks**
2. Click **+ Add New Webhook**
3. 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:

1. [Login](https://zapier.com/app/login/) to your Zapier account
2. Click **Create Zap** from your Dashboard
3. Search for **Webhooks by Zapier** (this is a [premium app](https://zapier.com/help/create/basics/learn-key-concepts-in-zapier#step-14))
4. Under Choose Trigger Event, select **Catch Hook**
5. Click **Continue**
6. Copy the generated Payload URL
7. Return to Shortcut, paste the Payload URL, and click **Add New Webhook**
8. Switch back to Zapier and click **Continue**

### Test the Connection

To verify Zapier is receiving Shortcut events:

1. In Zapier, click **Test & Review** to start listening for events
2. Go to Shortcut and trigger an event (e.g., move a Story, add a label)
3. 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