NAV
API Documentation:

We changed our name!

Clubhouse is now called Shortcut!

This change impacts Outgoing Webhooks in two ways:

Shortcut Outgoing Webhooks

Introduction

You can use webhooks to get notified about events that happen in your Shortcut organization. If you have any trouble or questions about using our Outgoing Webhooks API, check out our Help Center or just contact us - we’re happy to help!

Status

This is the v1 version of our Outgoing Webhook API. There may be breaking changes, but we will document them in a Change Log section on this page.

Use Cases

An Outgoing Webhook allows you to register a URL that Shortcut notifies whenever any change happens in your Organization. Webhooks track changes made by users in your account, and by changes made via Token requests. Webhooks allow you to use events that occur in Shortcut to trigger events in other services.

Here are some ideas to get you started…

Events

Shortcut’s outgoing webhooks fire whenever Stories or Epics are created, updated, or deleted. This includes all changes to comments and tasks as well, and even workflow state changes from Version Control integrations like GitHub.

Webhook Format

Example Response

{
  "id": "595285dc-9c43-4b9c-a1e6-0cd9aff5b084",
  "changed_at": "2017-06-27T16:20:44Z",
  "primary_id": 16927,
  "member_id": "56d8a839-1c52-437f-b981-c3a15a11d6d4",
  "version": "v1",
  "actions": [
    {
      "id": 16927,
      "entity_type": "story",
      "action": "update",
      "name": "test story",
      "changes": {
        "started": {
          "new": true,
          "old": false
        },
        "workflow_state_id": {
          "new": 1495,
          "old": 1493
        },
        "owner_ids": {
          "adds": ["56d8a839-1c52-437f-b981-c3a15a11d6d4"]
        }
      }
    }
  ],
  "references": [
    {
      "id": 1495,
      "entity_type": "workflow-state",
      "name": "Ready for Deploy"
    },
    {
      "id": 1493,
      "entity_type": "workflow-state",
      "name": "Ready for Dev"
    }
  ]
}

The Webhook API sends a message about any change to a Story in your Organization. Each event has the following properties:

Name Type
id UUID
primary_id UUID or Integer
member_id UUID
changed_at Date
actions [ Action, … ]
references [ Reference, … ]

Also included in the Webhook object is an actions array. This array allows you to access changes to objects. It will include changes to the primary object and object effected by the event.

The actions map follows a standard format. The individual action will have the id, entity type and the type of action. Included in the action map is a changes map. With the changes map you can access the old and new values of attributes that where changed in the event.

More documentation on this subject is to come. In the meantime, experimenting with an example server will be the fastest and easiest way to both understand what data we send and what data you might be interested in using.

Signature

If you provide a secret when you create the Outgoing Webhook, it will include an HTTP header named Payload-Signature. The value of this header is a cryptographic hash encoded in hexadecimal.

The signature is computed by the HMAC-SHA-256 algorithm. The ‘message’ is the HTTP request body encoded in UTF-8. The ‘secret’ is the secret string you provided, also encoded in UTF-8.

Testing

Example Self-hosted Server

Example Server

var express = require('express');
var bodyParser = require('body-parser');
var app = express();

app.use(bodyParser());

app.post('/webhook', function (req, res) {
  var event = JSON.parse(req.body);
  console.log(event);
  res.send(200);
})

app.listen(3000, function () {
  console.log('Example webhook app listening on port 3000!');
});

This example server written in Node.js will print each event object as it is received. This assumes you’ve installed the express npm library locally using npm install express --save.

Hosted Server

The simplest way to see the data being delivered to your inbound webhook is to use a hosted solution like Webhook.site. A hosted server allows you to easily test and inspect an incoming HTTP request. Please use caution as Webhook.site is a third-party service - we cannot guarantee the privacy of information transmitted there.