How to Run a Test#

Antithesis provides webhook endpoints that allow you to run tests on demand. Generally, a customer will have a webhook for each distinct product that they test. Each webhook supports optional parameters that configure the test and how its results are reported.

Calling a webhook first fetches the relevant container images, which may be precisely specified by tag or digest with the antithesis.images parameter. After fetching the images, our system will build the test environment, run your test for a configured duration, and generate a triage report. A link to this report is emailed to the addresses specified with the parameter. Contact us if you prefer to receive your results in Slack, an issue tracker, or somewhere else.

Here is an example of calling a webhook with curl:

curl --fail -u 'user:password' /
-X POST https://<tenant><endpoint> /
-d '{"params": { "antithesis.integrations.type":"github",
    "antithesis.images":"my_images_with_version_list" } }'

Webhook workflow#

Antithesis tests are high-throughput but also high-latency. They should therefore be triggered by an automated system (for example with your CI server) rather than by a human being.

Your automated system should be configued to run tests at least nightly. Frequent testing has many benefits. Among them are better bisection capability around when bugs were introduced, richer data around whether we can find the bug every time, and lower risk of a bug going unnoticed and being released in production.

You should configure your CI system so that each night it:

  1. builds all of the containers associated with your Antithesis setup

  2. pushes them to our registry

  3. triggers the webhook.

If you are unable to configure your CI server to do this, or are having any other issues running your test, please contact us.

Webhook syntax#

Webhooks (basic)#

The following command runs a webhook:
curl --fail -u 'user:password' -X POST /

The webhook returns an HTTP status code to indicate success or failure at starting the test. This code does not contain your test results, which will be delivered asynchronously via email.


Curl (and similar tools) will exit successfully so long as the webhook returns anything at all, even if it returns a failure code. To check for success of the underlying webhook, you must ensure that a 200 or 202 code was returned. The examples on this page use the --fail flag in curl to check for success.

The following are the variables for the webhook call.


The basic auth user and password for your tenant.


Your tenant’s name.


The endpoint to run.

Webhooks (with parameters)#

Webhook take optional parameters that control test behavior. There are default parameters, which affect all webhooks, and custom parameters that your Antithesis consultant can create for your needs.

Parameters are passed as JSON according to the following template:

    "params": {
        "parameter1_name": "parameter1_value",
        "parameter2_name": "parameter2_value",

Here is an example of using curl to call a webhook with parameters:

curl --fail -u 'user:password' -X POST /
https://<tenant><endpoint> /
-d '{"params": { "param1_name": "param1_value", "param2_name":"param2_value" } }'

The webhook returns an HTTP status code to indicate success or failure at starting the test. This code does not contain your test results, which will be delivered asynchronously both via email and in a format appropriate for the integration type. For example, a "github" integration type will deliver an asyncronous response in the Github REST API for commit statuses to your Github callback URL.

Default webhook parameters#

The following default parameters can be used to configure any Antithesis webhook. Your consultant may create additional custom parameters if you want additional ways to parametrize your tests. All parameters are optional.

Recipients who will receive emailed links to the triage report produced by this test run. If this parameter is not specified, emails will be sent to the default users set up for the endpoint. Multiple recipients should be specified as a ; delimited list where each entry is an email address.



The image versions of the software that Antithesis will test. The images are specified as an optional registry, an image name and either a digest (which is recommended) or a tag. Images specified by digest will be tagged as latest within the the Antithesis environment.

Multiple images should be specified as a ; delimited list. Each entry is in this format: [REGISTRY/]NAME(:TAG|@DIGEST).

Example: container_1@sha256:12341234;registry/container_2:latest_tag

  • registry: if not specified, the default will be:$TENANT_NAME-repository/


The image version of your config image. Antithesis will pull this image version from the container registry. This should be a single image version formatted in the same way as those in the antithesis.images parameter.


A string description of your test run. The description will be in the headers of the generated report and of any emails triggered by the test run.


A string identifier used to filter property history in reports. In the resulting report, each property’s history is generated from all previous runs with the same antithesis.source parameter. This allows you to (for example) easily see the history of tests on a single branch.

The parameter is any text, but you will likely provide a source control descriptor.

The following parameters are automatically configured by integrations such as the Antithesis Github action. You will probably not set these parameters manually.


The CI / Source Control integration type.

Values: ["none", "github"]. Default value: "none".


The URL Antithesis will call back to post the test results.


A security token used to authenticate when calling back with results.