With mabl's webhook functionality, you can configure your workspace to post information to a webhook before tests are about to start or after tests have completed. This information can be useful if you want to create custom actions in your CI/CD workflow based on the status or outcome of your mabl tests. Possible use cases include:
- Setting up resources in your cloud before mabl tests run
- Cleaning up resources in your cloud after mabl tests finish executing
Generally speaking, calling webhooks allows you to chain an action in your workflow to a specific status or outcome in mabl tests. This guide outlines how to add a webhook to your workspace and what information you can obtain from a webhook payload.
Adding webhooks
- Click on Settings in the left-hand navigation panel.
- Select the Webhooks tab. If you have added any webhooks previously, they will appear in the Configured webhooks section.
The webhooks page
- In the Add webhook section, enter the name of your webhook in the Name field.
- Add the target URL to the URL field. Mabl will call this URL with a JSON payload describing the pending or completed execution.
- In the Settings section, indicate whether you'd like mabl to call the webhook endpoint before or after executing the tests. For more information on these two options, see the following sections: Call pre-execution and Call post-execution.
- If you'd like, you can turn off "Strict SSL validation." Mabl ensures all connections use valid SSL certificates, but some CI servers may use self signed certificates.
- Click Add to confirm your changes.
All webhooks for a given workspace are fired in parallel. Each webhook must complete in 60 seconds or less or it will be considered failed.
Call pre-execution
Mabl will send information on the triggered tests to the webhook endpoint before the test runs begin. One possible use case for calling pre-execution is a customer-side script that sets up an application database before the test starts.
Require a success response before executing plan: the endpoint must have a successful status of 2xx or 3xx for the test execution to continue. If the endpoint does not result in a successful status, the tests will be failed.
Message indicating that the webhook did not get a successful response.
Call post-execution
Mabl will send information on the test runs after all test executions are complete. This setting requires at least one execution outcome trigger:
- On failure: mabl posts to the webhook only if a test execution fails
- On success: mabl posts to the webhook only if all test executions are successful.
Tests with a stopped status do not trigger the post-execution webhook.
Webhook payloads
Webhook endpoints will receive a JSON payload containing information on status, outcome and details for the specific plan(s) and test(s) that ran. Here are some attributes included in the webhook payload:
| Attribute | Description |
| "success" | The "success" attribute has a value of "true" until a state of "terminated", "cancelled", or "failed" is encountered. |
| "status" | Possible status states include "queued", "scheduling", "scheduled", "succeeded", "failed", "cancelled", "completed." |
| "status_cause" | The default value for "status_cause" is null. If a test terminates in an unexpected way, such as termination by a user, or a test timeout, or another kind of error. |
| "plan" |
Information on the plan, including the plan name and labels. Ad hoc test runs will not have a plan payload. |
| "plan_execution" |
Information on the status of that particular plan run. Ad hoc test runs include information on "plan_execution" (a.k.a. plan run) despite the fact that they are not backed by an actual plan. This information is "synthetic" and is included to maintain consistency in the mabl backend. |
| "journeys" |
Information on the tests, including test name and labels. |
| "journey_executions" | Information on the status of specific test runs, including start and stop times and any associated test case IDs. |
| "href" | The API endpoint of the specific plan, plan run, test, or test run. |
| "results_href" | The results URL for a specific test run in the mabl app. |
| "tags" | The "tag" attribute is used to mark mabl auto-generated tests, such as smoke tests and link crawler tests. Tags are not user-editable. |
| "test_cases" | If you've associated a mabl test with an outside test case management tool, such as Zephyr, TM4J, or XRay, the payload will include the test case ID(s) for those tests. For more information on test case management, check out the guide. |
| "message_version" | Denotes the version of the mabl webhook payload. |
Tests are referred to as "journeys" in the webhook payload.
Sample pre-execution payload
{
"status": "queued",
"status_cause": null,
"success": true,
"plan": {
"id": "4ba4550d-df2b-4df2-8799-46c44dbb4b9e",
"name": "Print click and assert Plan",
"labels": [ "apple", "zebra"],
"href": "https://api.mabl.com/v1/schedule/runPolicy/4ba4550d-df2b-4df2-8799-46c44dbb4b9e",
"tags": []
},
"plan_execution": {
"status": "queued",
"status_cause": null,
"id": "d5b96d02-c45d-4d08-8684-de55411bcede",
"href": "https://api.mabl.com/v1/execution/runPolicyExecution/d5b96d02-c45d-4d08-8684-de55411bcede"
},
"journeys": [
{
"id": "c221c1f8-aa52-4fdb-a1bd-5ee5b408ac9f:0",
"name": "Print, then assert",
"labels": [ "apple", "zebra"],
"href": "https://api.mabl.com/v1/test/journey/c221c1f8-aa52-4fdb-a1bd-5ee5b408ac9f:0",
"tags": [
"training"
]
}
],
"journey_executions": [],
"start_time": null,
"stop_time": null,
"tags": [],
"results": [],
"message_version": "1.0.0"
}
Sample post-execution payload
{
"status": "succeeded",
"status_cause": null,
"success": true,
"plan": {
"id": "4ba4550d-df2b-4df2-8799-46c44dbb4b9e",
"name": "Print click and assert Plan",
"labels": [ "apple", "zebra"],
"href": "https://api.mabl.com/v1/schedule/runPolicy/4ba4550d-df2b-4df2-8799-46c44dbb4b9e",
"tags": []
},
"plan_execution": {
"status": "succeeded",
"status_cause": null,
"id": "d5b96d02-c45d-4d08-8684-de55411bcede",
"href": "https://api.mabl.com/v1/execution/runPolicyExecution/d5b96d02-c45d-4d08-8684-de55411bcede"
},
"journeys": [
{
"id": "c221c1f8-aa52-4fdb-a1bd-5ee5b408ac9f:0",
"name": "Print, then assert",
"labels": [ "apple", "zebra"],
"href": "https://api.mabl.com/v1/test/journey/c221c1f8-aa52-4fdb-a1bd-5ee5b408ac9f:0",
"tags": [
"training"
]
}
],
"journey_executions": [
{
"status": "completed",
"status_cause": null,
"success": true,
"name": "Print, then assert",
"journey_id": "c221c1f8-aa52-4fdb-a1bd-5ee5b408ac9f:0",
"journey_execution_id": "c221c1f8-aa52-4fdb-a1bd-5ee5b408ac9f:0",
"start_time": 1517612117504,
"stop_time": 1517612146280,
"href": "https://api.mabl.com/v1/execution/runPolicyExecution/4ba4550d-df2b-4df2-8799-46c44dbb4b9e/testScriptExecution/c221c1f8-aa52-4fdb-a1bd-5ee5b408ac9f:0",
"results_href": "https://app.mabl.com/workspaces/3627972b-a762-4a87-a3fb-97cde3e9c414/test/plan-executions/d5b96d02-c45d-4d08-8684-de55411bcede/journeys/c221c1f8-aa52-4fdb-a1bd-5ee5b408ac9f:0",
"test_cases": [
{
"id": "MABL-1234"
},
{
"id": "MABL-999"
}
]
}
],
"start_time": 1517612110113,
"stop_time": 1517612146368,
"tags": [],
"results": [
{
"success": true,
"name": "Print, then assert",
"results_href": "https://app.mabl.com/workspaces/3627972b-a762-4a87-a3fb-97cde3e9c414/test/plan-executions/d5b96d02-c45d-4d08-8684-de55411bcede/journeys/c221c1f8-aa52-4fdb-a1bd-5ee5b408ac9f:0"
}
],
"message_version": "1.0.0"
}
Troubleshooting
How do I set custom headers with mabl webhooks? How do I send credentials for my webhook (e.g. Basic auth)?
The mabl webhook payload cannot be edited. If you need to use basic auth credentials for your webhook, one workaround is to encode the credentials into the URL itself. (Example: https://username:password@example.com). For more information on this method, check out the MDN guide.
My webhooks are behind a firewall, how can mabl reach them?
Webhook requests will originate from mabl’s static IP addresses. To enable access to mabl traffic, add the static IP addresses to your firewall allowlist.
Can I edit the mabl webhook payload content?
The mabl webhook payload cannot be edited
My tests are not running due to a TIMEOUT error
Your webhooks calls must complete in 60 seconds, or tests that are using them as PRE_EXECUTION contingent (requires success) webhooks will be considered failed
My webhooks are getting 401 or 403 errors
These are authentication errors. Ensure that your webhooks are public so that mabl can reach them.