Skip to main content
New to Testkube? Unleash the power of cloud native testing in Kubernetes with Testkube. Get Started >

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.

note

Please visit our Blog, Empowering Kubernetes Tests with Webhooks for a tutorial on setting up webhooks for Slack and Grafana Dashboard.

Benefits of using Webhooks in Testkube​

Testkube uses webhooks to integrate with external systems, allowing you to effortlessly synchronize your testing workflows with other tools and platforms. These webhooks are designed to carry critical information regarding your tests as HTTP POST payloads. The information can include the execution and real-time status depending on how you configure it.

To leverage webhooks, you need to ensure that the platform that you want to send information to has an HTTPS endpoint to receive the events. Testkube also allows you to customize the payloads.

You can create a webhook from the dashboard, use the CLI, or create it as a custom resource. Before we show how it’s done, let’s understand a few scenarios where Webhooks in Testkube shine:

  • Incident Management & Response: Webhooks can be used to create incidents and alert on-call teams when a critical test fails. This ensures a timely response and avoids any potential disruption due to failures and bugs. With Testkube, you can configure incident management tools like PagerDuty and OpsGenie to receive alerts based on critical events for your tests.

  • Communication and Collaboration: You can configure Webhooks in Testkube to send alerts to your teams in your communication tool. This will notify your team of any critical event that needs attention and attend to it before the issue escalates. Some of the popular communications tools like Slack and MS Teams can be configured to receive alerts from Testkube.

  • Monitoring and Observability: Webhooks can also be used to send alerts and notifications to your monitoring and observability tools like Prometheus and Grafana. This provides visibility into your tests, alerts you, and ensures that timely corrective actions can be taken.

Creating a Webhook​

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

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

Dashboard menu - webhooks icon

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

Then, fill in the webhook details:

Dashboard webhook - create dialog 1

  • 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.

Dashboard webhook - create dialog 2

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.

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 webhook - resource identifier

Webhook Payload​

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

{"text": "event id {{ .Id }}"}
When you have selected an existing Webhook, its payload can be configured in Webhook Settings->Action.

Dashboard webhook - webhook settings action`

Dashboard webhook - webhook payload

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_PRO_URL: {{ index .Envs "TESTKUBE_PRO_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.

Helper methods​

We also provide special helper methods to use in the webhook template: executionstatustostring is the method to convert a pointer to a execution status to a string type. testsuiteexecutionstatustostring is the method to convert a pointer to a test suite execution status to a string type.

Usage example:

  - name: TEXT_COLOUR
    value: {{ if eq (.TestSuiteExecution.Status | testsuiteexecutionstatustostring ) "passed" }}"00FF00"{{ else }}"FF0000"{{ end }}

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

Dashboard webhook - webhook settings action`

Dashboard webhook - webhook headers

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.