Skip to content

Commit 26a1ed7

Browse files
zoltan-davidz4kn4fein
zoltan-david
and
z4kn4fein
authored
docs review: Webhooks - major updates (#580)
* - updated UI element names in the text - variables: tested and OK - X-ConfigCat- headers: tested an OK - signature: tested and NOT OK; amikor van VARIABLE a bodyban, akkor nem működik helyesen - signing codes: tested PHP only - all links tested - not tested: Connecting to Slack, Connection to MS Teams * Update website/docs/advanced/notifications-webhooks.mdx Co-authored-by: Peter Csajtai <[email protected]> --------- Co-authored-by: Peter Csajtai <[email protected]>
1 parent f7ad457 commit 26a1ed7

File tree

1 file changed

+48
-41
lines changed

1 file changed

+48
-41
lines changed

‎website/docs/advanced/notifications-webhooks.mdx

Lines changed: 48 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -7,34 +7,37 @@ description: Webhooks are a way to send notifications to your applications about
77
import Tabs from '@theme/Tabs';
88
import TabItem from '@theme/TabItem';
99

10-
Your application can be notified about Setting value changes in real-time. ConfigCat enables this by calling a public URL of your system (a so-called Webhook). You can add your Webhook URLs in the _Dashboard_.
10+
ConfigCat Webhooks can notify your applications when a feature flag or other Setting changes by calling a public HTTP endpoint on your end.
11+
This allows your applications to react almost immediately to updates.
12+
Webhooks add the speed of near real-time updates to the reliability of Polling, giving your applications a fast and robust way to stay in sync.
13+
To enable Webhooks, simply tell us which HTTP endpoint to call. ConfigCat will send a request to that URL whenever a change occurs.
1114

12-
## Adding Webhook
15+
## Adding a Webhook
1316

14-
1. Go to the <a href="https://app.configcat.com/webhook" target="_blank">Webhooks</a> tab.
15-
2. Set the Url and the HttpMethod.
16-
3. Optionally, you can add additional HTTP headers and a body to the request.
17+
1. Go to the <a href="https://app.configcat.com/webhook" target="_blank">Webhooks</a> screen.
18+
2. Click the **+ ADD WEBHOOK** button.
19+
3. Choose **when** webhook notifications should be sent by selecting the **Config** and **Environment** where changes should trigger the Webhook.
20+
4. Define **how** to notify your system by setting the **URL** and the **HTTP METHOD**. This tells us which endpoint to call.
21+
5. (Optional) Add custom HTTP headers and a request body if needed.
1722

1823
## Request body with variables
1924

20-
You can specify a Request body that will be sent as the payload of the HTTP request.
25+
You can customize the request body that will be sent with each Webhook call. ConfigCat will replace certain placeholders in the body with real values at runtime.
2126

22-
ConfigCat will replace the following variables in the request body:
23-
24-
| Variable | The values it gets replaced with |
27+
| Variable | Replaced with |
2528
| -------------------------- | ------------------------------------------------------------------------------------------------- |
26-
| **##ConfigName##** | The name of the Config your setting belongs to. |
27-
| **##ConfigId##** | ID of the Config. |
28-
| **##EnvironmentName##** | The name of the Environment where the Setting value changed. |
29-
| **##EnvironmentId##** | ID of the Environment. |
29+
| **##ConfigName##** | The name of the Config where the change happened. |
30+
| **##ConfigId##** | ID of the Config where the change happened. |
31+
| **##EnvironmentName##** | The name of the Environment where the change happened. |
32+
| **##EnvironmentId##** | ID of the Environment where the change happened. |
3033
| **##URL##** | A direct link to the Config in the _ConfigCat Dashboard._ |
3134
| **##ChangeNotes##** | The **Mandatory notes** added to the actual changeset. |
3235
| **##ChangedBy##** | The name and email address of the user who made the changes. |
33-
| **##ChangeDetails##** | Details of the change in JSON format including setting name, old, new values and Targeting Rules. |
34-
| **##ChangeDetailsTeams##** | Details of the change in MS Teams format. |
35-
| **##ChangeDetailsSlack##** | Details of the change in Slack message format. |
36+
| **##ChangeDetails##** | Detailed change info in JSON format, including the name of the Setting or feature flag, old and new values and Targeting Rules. |
37+
| **##ChangeDetailsTeams##** | Change details formatted for Microsoft Teams. |
38+
| **##ChangeDetailsSlack##** | Change details formatted for Slack. |
3639

37-
The structure of the JSON array injected into the **##ChangeDetails##** looks like the following:
40+
The ##ChangeDetails## variable is replaced with a JSON array in the following format:
3841

3942
```
4043
[
@@ -54,27 +57,29 @@ The structure of the JSON array injected into the **##ChangeDetails##** looks li
5457
## Testing your Webhook
5558

5659
1. Change some of your settings in the _ConfigCat Dashboard._
57-
2. Click **SAVE & PUBLISH SETTINGS**.
60+
2. Click **SAVE & PUBLISH CHANGES**.
5861
3. Check if your Webhook was called correctly.
5962

6063
:::info
61-
**Developer Tip:** Running your Webhook on `localhost`? Expose it to the public internet temporarily by using a tool like <a href="https://ngrok.com/" target="_blank">ngrok</a>. This enables ConfigCat to call your webhook even in your local development environment.
64+
**Developer Tip**
65+
- Running your Webhook on `localhost`? Expose it to the public internet temporarily by using a tool like <a href="https://ngrok.com/" target="_blank">ngrok</a>. This enables ConfigCat to call your webhook even in your local development environment.
66+
- Just interested in what ConfigCat sends? Try [Webhhok.site](https://webhook.site/). This allows you to catch HTTP requests and see their content without requiring your to run anything anywhere.
6267
:::
6368

6469
## Verifying Webhook requests
6570

66-
To ensure the requests you receive are actually sent by ConfigCat, we highly recommend to verify
67-
the signature sent in the request headers by comparing it with your own calculated signature.
71+
To make sure the requests you receive are actually sent by ConfigCat, we strongly recommend verifying the signature included in the request headers.
72+
You can do this by comparing the received signature with one you compute using your signing key.
6873

69-
Each webhook request contains the following headers:
74+
Each webhook request includes the following headers:
7075

7176
| Header | Description |
7277
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------- |
73-
| `X-ConfigCat-Webhook-ID` | The webhook request's unique identifier. Different in every request. |
74-
| `X-ConfigCat-Webhook-Timestamp` | The time the webhook was sent in unix timestamp format. (seconds since epoch) |
75-
| `X-ConfigCat-Webhook-Signature-V1` | The list of the `base64` encoded HMAC-SHA-256 signatures. (comma delimited, 1 signature for each signing key) |
78+
| `X-ConfigCat-Webhook-ID` | A unique ID for the webhook request. This is different for every request. |
79+
| `X-ConfigCat-Webhook-Timestamp` | The time the request was sent, in Unix timestamp format (seconds since epoch). |
80+
| `X-ConfigCat-Webhook-Signature-V1` | A comma-separated list of base64-encoded HMAC-SHA-256 signatures (one for each signing key). |
7681

77-
Currently the latest (and the only) signature header version is `V1`. If the signing process is going to be changed in the future, more headers will be added with incremented version postfix.
82+
Currently, the latest (and the only) signature header version is `V1`. If the signing process changes in the future, new headers will be added with incremented version numbers.
7883

7984
Example request:
8085

@@ -358,23 +363,27 @@ public class Main {
358363

359364
### Timestamp validation
360365

361-
To prevent replay attacks, you can determine whether the request is within your timeframe tolerance by comparing the timestamp value received in the `X-ConfigCat-Webhook-Timestamp` header with your system's actual timestamp. If the signature is valid but the timestamp is too old, you can reject the request.
366+
To prevent replay attacks, you can check if the request was sent within an acceptable time window.
367+
Compare the timestamp from the `X-ConfigCat-Webhook-Timestamp` header with your system's current time.
368+
If timestamp is too old, you can safely reject the request.
362369

363-
Also, as the timestamp is part of the signed content, an attacker can't change it without breaking the signature.
370+
Since the timestamp is part of the signed content, an attacker cannot modify it without invalidating the signature.
364371

365372
## Retries
366373

367-
When ConfigCat notices that a webhook request might not delivered successfully (either due to network instabilities or when we receive a non-2XX status response), it attempts to retry the request at most 5 times with variable frequency.
374+
If ConfigCat detects that a Webhook request may not have been delivered successfully
375+
(for example, due to network issues or a non-2XX response),
376+
it will retry the request up to 5 times, using variable delays between attempts.
368377

369378
## Connecting to Slack
370379

371380
A few steps to set up Slack and get a message when a setting changes:
372381

373-
1. Define a <a href="https://api.slack.com/incoming-webhooks" target="_blank">Slack Incoming Webhook</a> and copy the Webhook URL.
374-
2. Go to the <a href="https://app.configcat.com/webhook" target="_blank">Webhooks</a> tab in the _ConfigCat Dashboard._
375-
3. Create a Webhook and add your Slack URL.
376-
4. Select POST as HTTP method.
377-
5. Add a request body like so:
382+
1. In Slack, create an <a href="https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks#create_a_webhook" target="_blank">Incoming Webhook</a> and copy the **Webhook URL**.
383+
2. In ConfigCat, go to the <a href="https://app.configcat.com/webhook" target="_blank">Webhooks</a> screen, and click **+ ADD WEBHOOK**.
384+
3. Paste Slack's **Webhhok URL** to ConfigCat's **URL** field.
385+
4. Select **POST** as the **HTTP METHOD**.
386+
5. Add the following request body:
378387

379388
```
380389
{
@@ -386,13 +395,11 @@ A few steps to set up Slack and get a message when a setting changes:
386395

387396
A few steps to set up Microsoft Teams and get a message when a setting changes:
388397

389-
1. Define an <a href="https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook#create-incoming-webhook-1" target="_blank">Incoming Webhook connector in Microsoft Teams</a> and copy the Webhook URL.
390-
2. Go to the <a href="https://app.configcat.com/webhook" target="_blank">Webhooks</a> tab in the _ConfigCat Dashboard._
391-
3. Create a Webhook and add your Teams URL.
392-
4. Select POST as the HTTP method.
393-
5. Add a request body similar to the one below.
394-
395-
Sample request body of the Webhook:
398+
1. In Microsoft Teams, create an <a href="https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook#create-incoming-webhook-1" target="_blank">Incoming Webhook</a> and copy the **Webhook URL**.
399+
2. In ConfigCat, go to the <a href="https://app.configcat.com/webhook" target="_blank">Webhooks</a> screen, and click **+ ADD WEBHOOK**.
400+
3. Paste Microsoft Teams' **Webhhok URL** to ConfigCat's **URL** field.
401+
4. Select **POST** as the **HTTP METHOD**.
402+
5. Add the following request body:
396403

397404
```
398405
{

0 commit comments

Comments
 (0)