Preflight Webhooks
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.

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.


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.
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 bypropertyKeyto the providedvalue. If the property does not exist, it will be added.add_value_to_list_property: Adds the providedvalueto a list property identified bypropertyKey. 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?
