Skip to content

Commit 73b4d1d

Browse files
ManuelGerdingManuelGerding
authored
feat: Documenting preflight webhooks (#142)
* feat: Documenting webhooks
1 parent 93e4b1f commit 73b4d1d

File tree

3 files changed

+318
-32
lines changed

3 files changed

+318
-32
lines changed

‎integrate-with-steadybit/slack-notifications.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -4,14 +4,14 @@ title: Slack Notifications
44

55
# Slack Notifications
66

7-
You want to receive a Slack message whenever an experiment has started or failed? This can be achieve via `Settings / Application Settings / Integrations / Slack`.
7+
You want to receive a Slack message whenever an experiment has started or failed? This can be achieve via `Settings` -> `Integrations` -> `Slack`.
88

99
> If you use an on-prem installation make sure to set the `STEADYBIT_WEB_PUBLIC_URL`, so we can add links to open Steadybit via links in the message.
1010
1111
| | |
12-
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
12+
|--------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|
1313
| **Name** | The name for this integration will not show up in the message. |
14-
| **URL** | The Slack webhook URL, which you can create in Slack by navigating Manage apps > Custom Integrations > Incoming Webhooks. |
14+
| **URL** | The Slack webhook URL, which you can create in Slack by navigating `Manage apps` -> `Custom Integrations` -> `Incoming Webhooks`. |
1515
| **Channel** | <p>The Slack channel which receives the message. If omitted the default from the Slack Webhook configuration will be used.<br><strong>optional</strong></p> |
1616
| **Icon Url** | <p>You may specify a different icon to be used for the message.<br><strong>optional</strong></p> |
1717
| **Team** | If no team is specified, you'll receieve all events. If you do specify a team you'll only receive notifications relevant for this team |

‎integrate-with-steadybit/webhooks/custom-webhooks.md

+146-9
Original file line numberDiff line numberDiff line change
@@ -4,19 +4,156 @@ title: Custom Webhooks
44

55
# Webhooks
66

7-
Custom webhooks are triggered by Steadybit whenever e.g. an experiment has started or failed. You can configure them at `Settings / Application Settings / Integrations / Custom webhook`. The content type is `application/json` and the message is described in our [OpenAPI specification](https://platform.steadybit.com/api/spec) as `WebhookPayload`.
7+
Custom webhooks are triggered by Steadybit whenever an experiment has progressed or the killswitch's status changes.
8+
9+
## Configure
10+
11+
You can configure custom webhooks at `Settings` -> `Integrations` -> `Custom webhook`.
12+
The content type is `application/json`, and the message is described in our [OpenAPI specification](https://platform.steadybit.com/api/spec) as `WebhookPayload`.
813

914
| | |
10-
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
15+
|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
1116
| **Name** | The name for this integration will not show up in the JSON body. |
12-
| **URL** | The URL, which will receive a HTTP Post request with the JSON body |
13-
| **Secret** | <p>You may a specify a secret which will be used to sign the body. <a href="/integrate-with-steadybit/webhooks/custom-webhooks.md#verifying-the-signature">Verifying the signature.</a><br><strong>optional</strong></p> |
14-
| **Team** | If no team is specified, you'll receieve all events. If you do specify a team you'll only receive events relevant for this team |
15-
| **Events** | You may select the events you want to recieve. |
17+
| **URL** | The URL, which will receive an HTTP Post request with the JSON body |
18+
| **Secret** | <p>You may specify a secret that will be used to sign the body. <a href="/integrate-with-steadybit/webhooks/custom-webhooks.md#verifying-the-signature">Verifying the signature.</a><br><strong>optional</strong></p> |
19+
| **Team** | If no team is specified, you'll receieve all events. If you do specify a team, you'll only receive events relevant to this team |
20+
| **Events** | Choose the events you want to receive. |
21+
22+
## Supported Events
23+
24+
You can decide to react to the following events individually or get informed about all events.
25+
26+
### Experiment Executions
27+
28+
The body contains the event identifier (`event`), the `time`, and the experiment `execution` (see below).
29+
30+
| Event | Event Identifier | Description |
31+
|----------------------|---------------------------------------|-----------------------------------------------------------------------------------------------------------------------------|
32+
| **Created** | `experiment.execution.created` | A new experiment execution was just started. As soon as all required agents have connected, the first step will be executed |
33+
| **Step Started** | `experiment.execution.step-started` | One step of a running experiment started. |
34+
| **Step Completed** | `experiment.execution.step-completed` | One step of a running experiment completed successfully (e.g. a check succeeded or the attack was performed). |
35+
| **Step Failed** | `experiment.execution.step-failed` | One step of a running experiment failed (e.g. a check didn't match the defined expectation). |
36+
| **Step Errored** | `experiment.execution.step-errored` | One step of a running experiment errored (e.g. a check or attack couldn't be executed due to a technical error). |
37+
| **Canceled** | `experiment.execution.step-canceled` | The experiment execution was canceled, e.g., by a user. |
38+
| **Completed** | `experiment.execution.completed` | The experiment completed succesfully, e.g., all steps have been completed successfully. |
39+
| **Failed** | `experiment.execution.failed` | The experiment execution failed because at least one step failed. |
40+
| **Errored** | `experiment.execution.errored` | The experiment execution errored because at least one step errored. |
41+
| **Preflight Checks** | `experiment.execution.preflight` | A [preflight webhook check](./preflight-webhooks) is performed before the experiment is allowed to start. |
42+
43+
### Killswitch
44+
45+
The body contains the event identifier (`event`), the `time` and the `killswitch`'s state (see below).
46+
47+
| Event | Event Identifier | Description |
48+
|-------------------------------|-------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
49+
| **Engaged Emergency Stop** | `killswitch.disengaged` | The [emergency stop](/use-steadybit/experiments/emergencyStop) was triggered to stop all experiment runs and prevent future runs. |
50+
| **Disengaged Emergency Stop** | `killswitch.engaged` | The [emergency stop](/use-steadybit/experiments/emergencyStop) was disengaged to allow future experiment runs. |
51+
52+
53+
## Developing Webhooks
1654

17-
#### Verifying the Signature
55+
A webhook uses an HTTP POST request at an endpoint reachable from the Steadybit platform.
56+
The HTTP request sends a body with the content-type `application/json`.
57+
Our [OpenAPI specification](https://platform.steadybit.com/api/spec) describes the exact body in `WebhookPayload`.
1858

19-
If a secret is provided a signature of the body is computed using `HMAC SHA-256` and sent as `X-SB-Signature` http header. You can use this header to verify the message.
59+
### Examples
60+
61+
This section covers some example requests to ease developing the webhook endpoint.
62+
63+
#### Experiment Execution Created
64+
65+
The request body that is sent to your endpoint depends on the specific experiment that is executed.
66+
67+
```bash
68+
curl --request POST \
69+
--url https://<your-custom-webhook-endpoint> \
70+
--header 'accept: */*' \
71+
--header 'accept-encoding: gzip' \
72+
--header 'content-type: application/json' \
73+
--data '{
74+
"event": "experiment.execution.created",
75+
"time": "2024-01-01T00:00:00.000000000Z",
76+
"execution": {
77+
"id": 78151,
78+
"experimentKey": "ADM-1",
79+
"teamKey": "ADM",
80+
"environment": "a7efb4f1-9b8e-46a7-a3eb-ffc29ba75eae",
81+
"name": "Stress CPU",
82+
"created": "2024-01-01T00:00:00.000000Z",
83+
"createdVia": "UI",
84+
"experimentVersion": 0,
85+
"state": "CREATED",
86+
"steps": [
87+
{
88+
"id": "0192fc6e-b1b8-7593-a2d6-ed9443172ba0",
89+
"state": "CREATED",
90+
"ignoreFailure": false,
91+
"parameters": {
92+
"cpuLoad": "1",
93+
"workers": 0,
94+
"duration": "30s"
95+
},
96+
"actionId": "com.steadybit.extension_container.stress_cpu",
97+
"actionKind": "ATTACK",
98+
"radius": {
99+
"targetType": "com.steadybit.extension_container.container",
100+
"percentage": 100,
101+
"predicate": {
102+
"operator": "AND",
103+
"predicates": [
104+
{
105+
"key": "k8s.deployment",
106+
"operator": "EQUALS",
107+
"values": [
108+
"gateway"
109+
]
110+
}
111+
]
112+
}
113+
},
114+
"targetExecutions": [
115+
{
116+
"type": "com.steadybit.extension_container.container",
117+
"name": "aa815cb361e65806a6938670d71a7af94666cf3a08acce990c1d131ae4533b07",
118+
"attributes": [
119+
{
120+
"key": "aws.account",
121+
"value": "244471902119"
122+
}
123+
]
124+
}
125+
],
126+
"totalTargetCount": 1
127+
}
128+
]
129+
}
130+
}'
131+
```
132+
133+
#### Killswitch Disengaged
134+
135+
```bash
136+
curl --request POST \
137+
--url https://<your-custom-webhook-endpoint> \
138+
--header 'accept: */*' \
139+
--header 'accept-encoding: gzip' \
140+
--header 'content-type: application/json' \
141+
--data '{
142+
"event": "killswitch.disengaged",
143+
"time": "2024-01-01T01:00:00.000000Z",
144+
"killswitch": {
145+
"engagedBy": "99c9ed40-6b85-439c-bd14-04787f2443d2",
146+
"engaged": "2024-01-01T00:00:00.000000Z",
147+
"disengagedBy": "e7ff1799-0430-4b1f-a835-c383b2a19543",
148+
"disengaged": "2024-01-01T01:00:00.000000Z"
149+
}
150+
}'
151+
```
152+
153+
### Verify Webhook Requests
154+
155+
If a secret is provided a signature of the body is computed using `HMAC SHA-256` and sent as `X-SB-Signature` http header. You can use this header to verify the
156+
message.
20157

21158
Here is an example of doing this in Java:
22159

@@ -33,4 +170,4 @@ private static boolean validateSignature(byte[] body, String secret, String head
33170
//compare using time-constant algorithm
34171
return MessageDigest.isEqual(signature, receivedSignature);
35172
}
36-
```
173+
```

0 commit comments

Comments
 (0)