If you're writing a custom integration with Shortcut and need to register a webhook that will receive updates via Shortcut's Webhooks API, you can use our REST API to set up your webhook programmatically.
Authentication
All of these routes expect a Shortcut token to be provided via the Shortcut-Token header. Shortcut users of your extension need to provide you a Shortcut API token generated by a non-Observer member of their workspace to perform these operations.
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:
-
webhook_url: the url where the webhook payloads should be sent (required) -
secret: a string value used to verify the payload. When your secret token is set, Shortcut uses it to create a hash signature with each payload that is passed along in the Payload-Signature header. Shortcut uses an HMAC hexdigest to compute the hash. (optional)
Response
The important field for most usage is the id. We'll use the id 500107362 in the examples that follow.
{
"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"
}
Get a Webhook Integration
Request
For an example webhook whose id is 500107362:
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
For an example webhook whose id is 500107362:
DELETE https://api.app.shortcut.com/api/v3/integrations/webhook/500107362
Shortcut-Token: your-tokenUpdated