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.

To create a new webhook, navigate to the Project > Admin > Webhook page. Select the New Webhook button and fill in the following fields:

• Action – The value for this field determines which events in Squish will trigger sending an update to the associated URL. Options are:
  • On Issue Submit
  • On Issue Update
• URL – This is the URL where the data payload will be sent.
• Secret – If specified, webhook requests will include an X-Squish-Signature header, which is an HMAC digest of the payload signed with this secret.
• Payload Format – This field determines the payload format based on the service for which this webhook will be used. Confidential issues will only trigger "Standard" webhooks. Options are:
  • Standard
  • Teams (used for sending payloads to a specific channel in Microsoft Teams) See Microsoft’s website for more information on setting up the Teams channel to accept Squish webhooks. 

When finished, select the Create Webhook button to save.

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.

Teams Payload Format

For webhooks configured to use the Teams Payload Format, the following data is sent as part of the payload:

On Issue Submit:

• Subject
• Date Created
• Assigned to
• Description
• Link to view the issue
• All values for fields which are not Confidential 

On Issue Update:

• Issue Number
• Subject
• Date/Time Modified
• Comment submitted with the update
• Link to view the issue
• All field value updates which are not Confidential
• If a Commit is included: The commit hash, ref, author name, and commit message.
• If a Workflow was used: The name of the workflow, and any field changes executed by the workflow.

Sample Standard 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 Standard 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()