Webhooks

Webhooks are a feature whereby you can specify HTTP/HTTPS endpoints that Squish will notify upon any issue submission or update for a given project. Think of them as push notifications, except instead of notifying your phone, Squish notifies a web service you create.

Technical details

When an issue is submitted or updated, Squish creates a JSON "payload" that will be POSTed to the webhooks configured HTTP/HTTPS endpoint. Both types of payloads (update and submit) are JSON objects that contain a bug object with all the field values in the issue, a project key containing the name of the project, and a url key containing the URL of the bug.

Update payloads will also contain a changes object if there were field updates, a comment object if a new comment was posted, and an updated_by key containing the name of the updated user.

Finally, the request will contain an X-Squish-Action header with a value of either submit or update.

Sample submit payload

{
  "project": "Weddings", 
  "url": "https://www.squishlist.com/imsadmin/weddings/13/", 
  "bug": {
    "Status": "Open", 
    "Assigned To": "Watson, Dan", 
    "Submitted By": "Watson, Dan", 
    "Date Modified": "2015-02-11 17:02:54", 
    "Description": "Save the Journey for last.", 
    "Confidential": false, 
    "Resolution": null, 
    "Resolved By": null, 
    "Date Submitted": "2015-02-11 17:02:54", 
    "Priority": "Normal", 
    "Date Resolved": null, 
    "Issue ID": 11, 
    "Wedding": "Jones-Smith", 
    "Task Type": "Music", 
    "Due Date": "2015-02-28", 
    "Type": "Action Item", 
    "Subject": "Create a playlist"
  }
}

Sample update payload

{
  "project": "Weddings", 
  "url": "https://www.squishlist.com/imsadmin/weddings/12/", 
  "comment": {
    "comment": "This is taken care of.", 
    "is_resolution": false, 
    "user": "Watson, Dan", 
    "confidential": false
  }, 
  "changes": {
    "Status": {
      "old": "In Progress", 
      "new": "Fixed/Completed"
    }
  }, 
  "bug": {
    "Status": "Fixed/Completed", 
    "Assigned To": "Watson, Dan", 
    "Submitted By": "Watson, Dan", 
    "Date Modified": "2015-02-11 16:59:55", 
    "Description": "at exxon", 
    "Confidential": false, 
    "Resolution": null, 
    "Resolved By": null, 
    "Date Submitted": "2013-04-02 14:13:30", 
    "Priority": "Normal", 
    "Date Resolved": null, 
    "Issue ID": 10, 
    "Wedding": "Jones-Smith", 
    "Task Type": "Transportation", 
    "Due Date": "2015-03-01", 
    "Type": "Purchase Order", 
    "Subject": "Buy gas for the limo"
  }, 
  "updated_by": "Watson, Dan"
}

Secrets and signatures

In order to verify that requests to your endpoint are coming from Squish, you can optionally provide a secret string when configuring webhooks. If provided, an HMAC is generated using your secret key and the entire POST payload (encoded as UTF-8), and put in a header named X-Squish-Signature.

For example, to verify a request in Django is a simple one-liner:

assert request.META['HTTP_X_SQUISH_SIGNATURE'] == hmac.new('secret', request.body.encode('utf-8')).hexdigest()