Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Preflight Webhooks

Preflight webhooks are an enterprise feature. Please reach out to us if you want to get access.

Preflight webhooks are triggered by Steadybit whenever an experiment is about to start and allow you to prevent an experiment from running. To decide whether that specific experiment run is allowed to start, you get a list of all the targets expected to be affected in the webhook call. Please note that, due to concurrency, this list may change: a target may be gone by the time the actual step starts, or new ones may be discovered.

Configure

You can add preflight webhooks at Settings → Integrations → Preflight webhook.

Add Preflight Webhook

A webhook has the following parameters to be specified:

Name

The preflight webhook's name, as shown in the experiment run.

URL

The URL that will receive an HTTP POST request with the HTTP request body.

Secret

You may specify a secret which is used to sign the body to verify the webhook request. optional

Team

If no team is specified, preflight checks will be performed for all teams. If you specify a team, preflight checks are only performed for that team.

Events

Right now, there is only one event here: Execution preflight checks, which is triggered before starting an experiment run.

Experiment Runs

During the experiment run, you can see the triggered preflight webhooks. If a webhook fails, the experiment run fails, and no targets are attacked.

Preflight Webhook Success
Preflight Webhook Failure - Stopped Experiment Run

Developing Webhooks

A webhook uses an HTTP POST request at an endpoint reachable from the Steadybit platform. The HTTP request sends a body with the content-type application/json. Our OpenAPI specification describes the exact body in WebhookPayload.

The webhook must return an HTTP status 2xx to allow an experiment to run. The experiment will not run if the webhook returns an HTTP status code other than 2xx.

Optionally, you can return a message in the HTTP response to show why the experiment isn't allowed to start. The response body can be found in the OpenAPI specification as PreflightWebhookResponseAO.

Lifecycle of Preflight Webhooks

A preflight webhook can be in one of the following lifecycle statuses, indicated in the experiment run:

CREATED

The preflight webhook was created and has sent the request to the configured webhook. It is still waiting for the response.

SUCCESSFUL

The preflight webhook was resolved successfully with an HTTP status code 2xx. The experiment is allowed to continue (if all preflight webhooks are successful).

FAILED

The preflight webhook resolved with a non-2xx HTTP status code. The experiment will fail. Optionally, the response may contain a message as a reason for experiment failure.

ERRORED

A technical error occurred while requesting the HTTP endpoint, e.g., the URL couldn't be resolved, or the HTTP request timed out.

A webhook will time out after 55 seconds. In that case, the preflight check is marked as ERRORED, and the experiment will not start. If the webhook resolves later, the actual result will be submitted to the preflight check step in the experiment.

Examples

This section covers some example requests to ease the development of the preflight webhook endpoint. The request body sent to your endpoint depends on the experiment being executed.

Request

The curl command below can be used to mock a preflight request from Steadybit to your endpoint.

Please note that some of the metadata (i.e., step's parameters, and targetExecutions' attributes) have been omitted.

Response: Allow Run

The webhook must return an HTTP status 2xx to allow an experiment to run.

Optionally, you can return a message in the HTTP response to show details on why the experiment is allowed to start. For example:

Response: Disallow Run

To disallow an experiment to run, the webhook must return an HTTP status code other than 2xx.

Optionally, you can return a message in the HTTP response to show why the experiment isn't allowed to start.

Response: Property Modifications

Preflight Webhooks can also modify properties of the experiment execution by returning modifications in the response body. Examples:

Currently, two modification types are supported:

  • set_property_value: Sets the value of a property identified by propertyKey to the provided value. If the property does not exist, it will be added.

  • add_value_to_list_property: Adds the provided value to a list property identified by propertyKey. If the property does not exist, it will be added. If it exists but is not a list, the execution will fail.

Properties need to be editableInExecution if inherited from the experiment design. You can learn more about properties here.

Verify Webhook Requests

Once the webhook's optional secret is configured, you can verify that a call to the preflight webhook is legitimate by checking its signature. The body's signature is computed using HMAC SHA-256 and sent as an X-SB-Signature HTTP header.

You can use this header to verify the message. Here is an example of doing this in Java:

Last updated

Was this helpful?