Sample Jira Webhook (Versions: 10.0+)

Versions: 8.0+

QuerySurge has long emphasized team communication and information-sharing in its design. As part of that emphasis, webhook support has been introduced in QuerySurge 10.0. This article describes the basic setup to send a webhook message to Jira.

QuerySurge installs with a prebuilt sample Jira webhook that creates a bug in Jira, which you can either use as-is, or modify for your needs:

Results: Create Jira Bug on Fail

A Sample Jira Webhook (Bug creation)

Jira does not have an explicit feature for incoming webhooks (so there is no setup), however Jira does have a REST API, and in the following example, we use this API as a webhook to create a bug in Jira. Bug creation usually only happens at the end of a Scenario, if the Scenario fails, so that is what we illustrate here. In addition, Jira requires authentication, which we show via Basic auth.

1. Edit the webhook name if you so choose.
   
   
2. Notice that the "Scenario Ended" event has been pre-selected, since this webhook provides a detail view of a Scenario execution.
   
   
3. Add an optional Description (as needed).
   
   
4. The Request Method of POST is almost invariably the method for any webhook (QuerySurge does support a PUT option).
   
   
5. The Provider in this example is Jira.
   
   
6. This is the specific URL for Jira REST API calls. Note that your server, port and version will most likely differ.
   
   
7. No special HTTP Headers are required for Slack webhooks (however other webhooks may have header requirements). There is a default Content-Type header that is generally required for any webhook.
   
   
8. The JSON payload in this example is simple to moderate in complexity. The JSON must follow Jira API syntax rules (consult the Jira API documentation). There are a few items of note here. First, the Jira project is identified not by the project name but by the Project Key ("WEBHOOK1" in this example), which was set when the project was created in Jira. You can see the key by viewing the project information in Jira. Second, note that you can insert QuerySurge values into the message, using the tool, in the upper right of the payload editor. (Values that you select are denoted by the ${...} syntax.) Finally, this example is a "plain-vanilla" bug-creation example, meaning there are no required custom fields. If you have required custom fields, you'll need to find out how they are named in the JSON (again, consult the documentation) and configure them with QuerySurge values or hardcoded values as needed.

   {
       "fields":{
           "project":{
               "key":"WEBHOOK1"
           },
           "summary":"Scenario ${scenarioName} has an outcome of: ${outcome}",
           "description":"Percent passing: ${passRate} %\nNumber of QueryPairs: ${numberOfQueryPairs}\n${queryPairsPassed} / ${numberOfQueryPairs} passed\n${queryPairsFailed} / ${numberOfQueryPairs} failed\n${queryPairsKilled}, ${queryPairWarnings}, ${queryPairErrors} killed, warning, errors\n\nRun Owner: ${owner}\nRun Start: ${startTime}\nRun End: ${endTime}\nDuration: ${duration}",
           "issuetype":{
               "name":"Bug"
           }
       }
   }

9. As noted, we have created an Event Filter in this example, so that the webhook is only sent (and therefore the Jira bug is only created) when the Outcome of the execution is 'Not Equal' to  'Passed'. Without setting this filter, we would create a bug in Jira for every QuerySurge execution. The webhook Event Filters are identical to Email Notification Event Filters. For more information, see this article.
   
   

10. Jira uses basic authentication with an API token to authenticate API requests. Information on how to create an API token in Jira can be found here. The API token an be applied to your webhook template using the basic authentication setting where:

    Username=<yourUsername>
    Password=<yourPersonalAPIToken>

11. At the bottom right, there is a Save button with an arrow at its right. When you click on the arrow, a popup Test Webhook button shows, which allows you to test your webhook setup with dummy data. Error messages are reported along the bottom of the window. Once your setup is working, use the Save button to save your webhook.
    
    
12. Your Jira bug looks like a standard bug, unless you have customized it: