Webhooks

With Webhooks, you can provide other applications with real-time information based on events that happen in TestRail.

Unlike typical API requests, where you would need to poll for data frequently in order to get new information as it is updated, webhooks let you send notifications and payloads to external systems or applications when certain events occur in TestRail like when your team adds new test cases, creates new test runs, or uploads new test results. This allows you to integrate TestRail with any application with an API, speed up key processes in your test cycle, and increase visibility into the progress of your testing activities for your entire team.

How to add a webhook

There are two different ways to add a webhook: globally (which will be triggered for any projects in your TestRail instance), or for specific projects.

To set up a webhook across all of your projects, go to Administration and click on Integration.

Choose the Webhooks tab. This is where you can add webhooks or edit existing ones.

Click Add Webhook to set up a new one. You will see the following window, which will allow you to add a name, specify payload URL, method, content type, and key information like headers and payload.

• Give your webhook a descriptive name.
• Add a Payload URL: This URL is where the webhook content will be sent to when it is triggered.
• Method: Choose between POST, GET, PUT, PATCH, or DELETE.
• Select a Content Type. Available options are:
  
  • application/json
  • application/x-www-form-urlencoded
  • application/xml
  • text/xml
  • text/plain
• Add any additional Headers you may need for your webhook. All webhooks in TestRail have some default Headers that are in gray, but you can also add custom headers that will appear in black.
• Add a Payload to your webhook. The Payload field is designed to be flexible so that you can construct or send almost any kind of payload you wish using the console. (See Payloads below for more information.)

• You can also set a Secret to your webhook for authentication purposes, if needed. This will be included in the webhook headers.
• Under Events, select which events you would like to trigger webhooks by checking the boxes to the left of each option
  
  • You can choose multiple events to trigger the same webhook
• Under Projects, check the boxes for each project where you would like your selected events to trigger this webhook.
• Finally, you can activate or deactivate the webhook by checking (or unchecking) the Active box.
• Click Save Settings when you’re ready.

Once you have configured a webhook, you can test the webhook settings using the Test button in the top right-hand side of the Add Webhook dialogue. Learn more about testing your webhooks configuration here.

Adding webhooks to specific projects

You can also add webhooks to specific projects via the Edit Project page. Go to Administration, click Projects from the menu in the right sidebar, and then click the pencil icon to go to the Edit Project page. Or, if you are already on the Project Overview page for a specific project, click Edit in the top right corner. Once you are on the Edit Projects page, click the Webhooks tab to add or edit a webhook specific to that project.

Testing and auditing webhooks

When adding a new webhook, it’s a good idea to test it before saving it so you can first review the request, payload, and response. You can test webhooks while initially configuring them in the Add Webhooks page, or return to an existing webhook to test it later. You can also review historical requests triggered by webhooks that you have set up in your Webhooks settings.

To test a webhook you have already created or review historical activity, navigate back to Integration under the Administration tab, and return to the Webhooks tab. Locate the Testing section at the right hand of the page. 

Here, you can see a log of the recent deliveries and the dates. Click on a recent delivery to review the information that was included in the headers and the payload of your webhook based on the specific event that triggered that delivery under the Request tab.

On the Response tab, you can see the status code for the response that TestRail received from your external application which received the webhook, as well as the headers and payload of the response.

Webhook events

When you set up a webhook in TestRail, you can choose specific events that will trigger it. Here is a list of the events that you can select to trigger webhooks at this time.

You can add a number of the variables to your payload to add more context and data to your webhook. See the full list below.

Payloads

The payload field available in the webhook console lets you construct and send almost any kind of payload you wish. This is an example of JSON payload structure to know the kind of things that can be done for Slack.

{
  "text": "%event_creator% created a new test case:",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*%event_creator% created a new test case:*"
      }
    },
    {
      "type": "divider"
    },
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*<%url%|%name%>* \n Priority: %case_priority% \n Type: %case_type%"
      }
    }
  ]
}

When the webhook is executed, the result is a message similar to this one in slack.

Payload variables

Different variables are available to supplement payloads. The variables available for use in webhooks payloads at this time are:

You can add the variables to the payload field and they will be populated with the corresponding TestRail data when the webhook is triggered like in the image below.

On-premise installation (TestRail Server)

Installing the TestRail Server version of TestRail 7.5 involves some additional, optional, steps directly related to the new webhooks features. During the installation or upgrade process you’ll be presented with an additional step during which you can configure a RabbitMQ message queue server to handle your outbound webhook payloads.

If you decide you do want to use a message queue for this purpose, then during your TestRail Server installation or upgrade, you’ll need to add:

• The RabbitMQ server name
• The RabbitMQ port number (5672 by default)
• The RabbitMQ username and password
• And optionally the RabbitMQ certificate and private key

The message queue settings can also be found and added or updated in the Administration > Site Settings console.