Webhook guide

Test IT features a webhook mechanism that makes it possible to send requests to an external handler when certain events occur in the system. It's convenient when integrating with external systems

Webhook Setup

For correct work with webhooks, you need to set the variable FRONTEND_URL in the .env file.

Webhooks can be configured by a user with Project editing / Editing or Project editing / Full access permission in a project. Go to the "Webhooks" tab in the project settings.

When creating a new webhook, indicate the following:

  • Name - the webhook's name as it will appear on the webhook list

  • Description - a text description of the webhook for entering a brief comment

  • Event - the action in the system that will cause a webhook to be sent

  • URL - the address of the external system to which the request will be made

  • Request type - select POST, PUT, or DELETE from the pop-up menu

  • Key-Value fields - the value for headers and the request's parameters

You can use special variables in the values of headers and request parameters to send data related to a specific event to an external system. A list of special variables is predefined for each event based on its context. Special variables available for substitution can be found in instructions and tooltips.

For a POST request, it is possible to send the context of the event in the body of the request. This means that a data model predefined for the event will be sent. Once all necessary data has been entered, save the webhook.

All webhooks sent are displayed in a transmission log that can be accessed from the webhook settings tab.

A webhook for the event "Autotests run was created"

The following special variables can be used in a webhook for the event "Autotests run was created":

Variable

Description

$AUTO_TESTS_COUNT

The number of autotests to be run

$BUILD

The build number indicated when the test plan was created

$PRODUCT_NAME

The product name entered when the test plan was created

$PROJECT_ID

The ID of the project associated with the autotests being run

$PROJECT_NAME

The name of the project associated with the autotests being run

$START_DATE

The test plan's start date

$TEST_PLAN_ID

The ID of the test plan within the framework of which the autotests are being run

$TEST_PLAN_URL

A link to the test plan in the Test IT system

$TEST_POINTS_COUNT

The number of test events to be run

$TEST_RUN_ID

The ID of the autotest run

$TESTIT_URL

A link to the Test IT system

$USER_NAME

The name of the user who ran the autotests

When the context of the event is sent in the body of the request, the following data structure will be transmitted:

[
{
"testRunId": "string",
"testPlanGlobalId": 0,
"productName": "string",
"build": "string",
"configurations": [
{
"entityTypeName": "string",
"createdDate": "2019-08-15T10:01:51.412Z",
"modifiedDate": "2019-08-15T10:01:51.412Z",
"createdById": "string",
"modifiedById": "string",
"name": "string",
"description": "string",
"isActive": true,
"capabilities": {},
"projectId": "string",
"globalId": 0,
"id": "string",
"isDeleted": true
}
],
"autoTests": [
{
"createdDate": "2019-08-15T10:01:51.413Z",
"modifiedDate": "2019-08-15T10:01:51.413Z",
"createdById": "string",
"modifiedById": "string",
"workItems": [
{
"createdDate": "2019-08-15T10:01:51.413Z",
"modifiedDate": "2019-08-15T10:01:51.413Z",
"createdById": "string",
"modifiedById": "string",
"isAutomated": true,
"attachments": [
{
"name": "string",
"fileId": "string",
"type": "string",
"size": 0,
"createdDate": "2019-08-15T10:01:51.413Z",
"modifiedDate": "2019-08-15T10:01:51.413Z",
"createdById": "string",
"modifiedById": "string",
"workItemId": "string",
"id": "string",
"isDeleted": true
}
],
"autoTests": [
null
],
"name": "string",
"entityTypeName": "string",
"projectId": "string",
"sectionId": "string",
"description": "string",
"state": "string",
"priority": 1,
"globalId": 0,
"steps": [
{
"action": "string",
"expected": "string",
"workItemId": "string"
}
],
"duration": 0,
"attributes": [
{
"attributeId": "string",
"value": "string"
}
],
"tags": [
{
"id": "string",
"name": "string",
"createdDate": "2019-08-15T10:01:51.413Z",
"modifiedDate": "2019-08-15T10:01:51.413Z",
"createdById": "string",
"modifiedById": "string"
}
],
"links": [
{
"id": "string",
"isDeleted": true,
"title": "string",
"url": "string",
"description": "string"
}
],
"id": "string",
"isDeleted": true
}
],
"autotestExternalId": "string",
"testLinkInRepository": "string",
"id": "string",
"isDeleted": true
}
],
"testPoints": [
{
"configurationGlobalId": 0,
"autoTestIds": [
"string"
]
}
],
"status": "string"
}
]

A webhook for the event "Change test plan status"

The following special variables can be used in a webhook for the event "Change test plan status":

Variable

Description

$BUILD

The build number indicated when the test plan was created

$PRODUCT_NAME

The product name entered when the test plan was created

$PROJECT_ID

The ID of the project with which the test plan is associated

$PROJECT_NAME

The name of the project with which the test plan is associated

$START_DATE

The start date of the test plan

$END_DATE

The end date of the test plan

$TEST_PLAN_ID

The ID of the test plan

$TEST_PLAN_NAME

The name of the test plan

$TEST_PLAN_STATUS

The status to which the test plan has been changed

$TEST_PLAN_DESCRIPTION

A description of the test plan

$TEST_PLAN_DURATION

The duration of the test plan

$TEST_PLAN_URL

A link to the test plan

$TESTIT_URL

A link to the Test IT system

$USER_NAME

The name of the user who changed the status of the test plan

When the context is sent in the body of the request, the following data structure will be transmitted:

{
"GlobalId": 0,
"StateName": "string",
"Name": "string",
"StartDate": "11/29/2019 14:37:00",
"EndDate": "11/29/2019 14:37:00",
"Description": "string",
"Build": "string",
"ProjectId": guid,
"ProductName": "string",
"Duration": "",
"Tags": [],
"Link": "string",
"IsDeleted": false
}

An example of using a webhook

Let's try sending a request to run a job in Jenkins using a webhook.

To do this, we create a webhook for the event "Autotests run was created" with the following parameters:

URL: http://jenkins.mycompanyname.com/job/testit-webinar/buildWithParameters

HTTP headers:

Key: authorization Value: Basic ** (the authorization token is hidden for security reasons)

URL parameters:

Key: testRunId Value: $TEST_RUN_ID

Key:: testProjectId Value: $PROJECT_ID

You can see the resulting request and a response from the external system in the logs:

Request:

Method: POST
RequestUri: 'http://jenkins.mycompanyname.com/job/testit-webinar
/buildWithParameters?testRunId=a62172c1-f067-4006-97c0-
e93aa8e8f3b5&testProjectId=301'
Version: 2.0
Content: <null>
Headers: { Authorization: Basic ****** }

Response:

StatusCode: 201
ReasonPhrase: 'Created'
Version: 1.1
Content: System.Net.Http.HttpConnection+HttpConnectionResponseContent
Headers:
{
Date: Fri, 26 Jul 2019 16:32:34 GMT
X-Content-Type-Options: nosniff
Location: http://jenkins.mycompanyname.com/queue/item/1777974/
Server: Jetty(9.4.z-SNAPSHOT)
Content-Length: 0
}

Jenkins has begun compiling the project with the parameters it received.