Webhooks

Webhooks allow you to integrate Testkube with external systems by sending HTTP POST payloads containing information about Testkube executions and their current state when specific events occur. To set up webhooks in Testkube, you'll need to have an HTTPS endpoint to receive the events and a payload template to be sent along with the data.

Creating a Webhook

The webhook can be created using the Dashboard, CLI, or a Custom Resource.

Dashboard

If you prefer to use the Dashboard, you can view existing webhooks by going to the Webhooks tab.

Here you can also create a new webhook by clicking the Create a new webhook button.

Then, fill in the webhook details:

• Name - your webhook name (in this case example-webhook)
• Resource identifier - the resource (or resources) selected by label for which the webhook can be triggered (in the example: test-type:postman-collection - any postman test)
• Triggered events - events that will trigger the webhook (in this case start-test, end-test-success, and end-test-failed). All available trigger events can be found in the Supported Event types section.

Set your webhook URI - the HTTPS endpoint where you want to receive the webhook events. After the webhook is created, the custom payload and headers can be set in Settings->Action.

CLI

Webhooks can be created with Testkube CLI using the `create webhook` command.

testkube create webhook --name example-webhook --events start-test --events end-test-success --events end-test-failed --uri <YOUR_ENDPOINT_URL>

--name - Your webhook name (in this case example-webhook). --events - Event that will trigger a webhook. Multiple --events can be defined (in this case --events start-test --events end-test-success --events end-test-failed). All available trigger events can be found in the Supported Event types section. --uri - The HTTPS endpoint where you want to receive the webhook events.

Custom Resource

webhook.yaml

apiVersion: executor.testkube.io/v1
kind: Webhook
metadata:
  name: example-webhook
  namespace: testkube
spec:
  uri: <YOUR_ENDPOINT_URL>
  events:
    - start-test
    - end-test-success
    - end-test-failed
  selector: ""

Where <YOUR_ENDPOINT_URL> should be replaced with the HTTPS endpoint URL where you want to receive the webhook events.

And then apply with:

kubectl apply -f webhook.yaml

Resource Selector (labels)

In order to limit webhook triggers to a specific resource, or resources, the Resource Selector can be used. It allows you to select the specific resource by label, or labels.

Dashboard

CLI

The Resource Selector can be set with --selector. For example, --selector test-type=postman-collection will limit the resources to the postman tests (label: test-type=postman-collection)

Custom Resource

spec:
  selector: test-type=postman-collection

So, the complete definition may look like this:

webhook.yaml

apiVersion: executor.testkube.io/v1
kind: Webhook
metadata:
  name: example-webhook
  namespace: testkube
spec:
  uri: <YOUR_ENDPOINT_URL>
  events:
    - start-test
    - end-test-success
    - end-test-failed
  selector: test-type=postman-collection

Webhook Payload

Webhook payload can be configured - in this example, event id:

{"text": "event id {{ .Id }}"}

Dashboard

Webhook payload can be configured in Webhook Settings->Action

CLI

Create a webhook payload template file:

template.json

{
  "text": "event id {{ .Id }}"
}

And set it with --payload-template template.json.

testkube create webhook --name example-webhook --events start-test --events end-test-passed --events end-test-failed --payload-template template.json --uri <YOUR_ENDPOINT_URL>

Where <YOUR_ENDPOINT_URL> should be replaced with the HTTPS endpoint URL where you want to receive the webhook events.

Expected output:

Webhook created example-webhook 🥇

Custom Resource

Payload template can be configured with spec.payloadTemplate.

  payloadTemplate: |
    {"text": "event id {{ .Id }}"}

Example:

apiVersion: executor.testkube.io/v1
kind: Webhook
metadata:
  name: example-webhook
  namespace: testkube
spec:
  uri: <YOUR_ENDPOINT_URL>
  events:
    - start-test
    - end-test-success
    - end-test-failed
  selector: ""
  payloadObjectField: ""
  payloadTemplate: |
    {"text": "event id {{ .Id }}"}

Webhook Payload Variables

Webhook payload can contain event-specific variables - they will be replaced with actual data when the events occurs. In the above examples, only the event Id is being sent. However, any of these supported Event Variables can be used.

For example, the following payload:

{"text": "Event {{ .Type_ }} - Test '{{ .TestExecution.TestName }}' execution ({{ .TestExecution.Number }}) finished with '{{ .TestExecution.ExecutionResult.Status }}' status"}

will result in:

{"text": "Event end-test-success - Test 'postman-executor-smoke' execution (948) finished with 'passed' status"}

testkube-api-server ENV variables

In addition to event-specific variables, it's also possible to pass testkube-api-server ENV variables:

template.txt

TESTKUBE_CLOUD_URL: {{ index .Envs "TESTKUBE_CLOUD_URL" }}

URI and HTTP Headers

You can add additional HTTP headers like Authorization or x-api-key to have a secret token. It's possible to use golang based template string as header or uri value.

Dashboard

Webhook headers can be configured in Webhook Settings->Action.

CLI

Custom headers can be set using `--header` - for example:

--header X-Token="12345"

Custom Resource

spec:
  headers:
    X-Token: "12345"

webhook.yaml

apiVersion: executor.testkube.io/v1
kind: Webhook
metadata:
  name: example-webhook
  namespace: testkube
spec:
  uri: <YOUR_ENDPOINT_URL>
  events:
    - start-test
    - end-test-success
    - end-test-failed
  selector: ""
  headers:
    X-Token: "12345"

Supported Event types

Webhooks can be triggered on any of the following events:

• start-test
• end-test-success
• end-test-failed
• end-test-aborted
• end-test-timeout
• start-testsuite
• end-testsuite-success
• end-testsuite-failed
• end-testsuite-aborted
• end-testsuite-timeout
• created
• updated
• deleted

They can be triggered by the following resources:

• test
• testsuite
• executor
• trigger
• webhook
• testexecution
• testsuiteexecution

Supported Event Variables

Event-specific variables:

• Id - event ID (for example, 2a20c7da-3b77-4ea9-a33d-403187d3e9e6)
• Resource
• ResourceId
• Type_ - event Type (for example, start-test, end-test,success, etc. All available trigger events can be found in the Supported Event types section).
• TestExecution - test execution details (example: TestExecution (Execution) section)
• TestSuiteExecution - test suite execution details (example: TestSuiteExecution section)
• ClusterName - cluster name
• Envs (API-server ENV variables) - list of Testkube API-Server ENV variables

The full Event Data Model can be found here.

TestExecution (Execution):

• Id - Execution ID (for example, 64f8cf3c712890925aea51ce)
• TestName - Test Name (for example, postman-executor-smoke)
• TestSuiteName - Test Suite name (if run as a part of a Test Suite)
• TestNamespace - Execution namespace, where testkube is installed (for example, testkube)
• TestType - Test type (for example, postman/collection)
• Name - Execution name (for example, `postman-executor-smoke-937)
• Number - Execution number (for example, 937)
• Envs - List of ENV variables for specific Test (if defined)
• Command - Command executed inside the Pod (for example, newman)
• Args - Command arguments (for example, run <runPath> -e <envFile> --reporters cli,json --reporter-json-export <reportFile>)
• Variables - List of variables
• Content - Test content
• StartTime - Test start time (for example, 2023-09-06 19:23:34.543433547 +0000 UTC)
• EndTime - Time when the test execution finished (for example, 2023-09-06 19:23:42.221493031 +0000 UTC)
• Duration - Test duration in seconds (for example, 7.68s)
• DurationMs - Test duration in miliseconds (for example, 7678)
• ExecutionResult - Execution result (https://github.com/kubeshop/testkube/blob/main/pkg/api/v1/testkube/model_event.go)
• Labels Test labels (for example, [core-tests:executors executor:postman-executor test-type:postman-collection],)
• RunningContext - Running context - how the test has been triggered (for example, user-ui)

The full Execution data model can be found here.

TestSuiteExecution:

• Id - TestSuiteExecution ID (for example, 64f8d5b2712890925aea51dc)
• Name - TestSuite name (for example, ts-executor-postman-smoke-tests-472)
• Status - TestSuite execution status (for example, running or passed)
• Envs - List of ENV variables
• Variables - List of variables
• StartTime - Test start time (for example, 2023-09-06 19:23:34.543433547 +0000 UTC)
• EndTime - Time when the test execution finished (for example, 2023-09-06 19:23:42.221493031 +0000 UTC)
• Duration - Test duration in seconds (for example, 7.68s)
• DurationMs - Test duration in miliseconds (for example, 7678)
• StepResults
• Labels - TestSuite labels (for example, [app:testkube testsuite:executor-postman-smoke-tests])
• RunningContext - Running context - how the TestSuite has been triggered (for example, user-ui)

The full TestSuiteExecution data model can be found here.

Additional Examples

Microsoft Teams

Webhooks can also be used to send messages to Microsoft Teams channels. First, you need to create an incoming webhook in Teams for a specific channel. You can see how to do it in the Teams Docs here. After your Teams incoming webhook is created, you can use it with Testkube webhooks - just use the URL provided (it will probably look like this: https://xxxxx.webhook.office.com/xxxxxxxxx).

In order to send the message when test execution finishes, the following Webhook can be used:

apiVersion: executor.testkube.io/v1
kind: Webhook
metadata:
  name: example-webhook-teams
  namespace: testkube
spec:
  events:
  - end-test-success
  - end-test-failed
  - end-test-aborted
  - end-test-timeout
  uri: https://xxxxx.webhook.office.com/xxxxxxxxx
  payloadTemplate: "{\"text\": \"Test '{{ .TestExecution.TestName }}' execution ({{ .TestExecution.Number }}) finished with '{{ .TestExecution.ExecutionResult.Status }}' status\"}\n"

It will result in:

{"text": "Test 'postman-executor-smoke' execution (949) finished with 'passed' status"}

and the message: Test 'postman-executor-smoke' execution (949) finished with 'passed' status" being displayed.

Testing Webhooks

If you are just getting started and want to test your webhook configuration, you can use public and free services that act as HTTP catch-all apps. Here are a couple of options:

1. Beeceptor: Beeceptor allows you to quickly capture HTTP payloads, review them in real time, and send desired HTTP responses as you test your webhooks. You can use its local-tunnel feature when you want to test payloads against a service running on localhost.
2. Webhook.Site: Webhook.Site provides an easy way to capture HTTP payloads, review the headers and body for the incoming requests, and automatically respond with a 200 OK status code.

By using these services, you can quickly set up an HTTP endpoint to receive webhook payloads during your testing/development process.