Update `cloud-notifications` documentation (#21105)
Co-authored-by: Ilya Mashchenko <ilya@netdata.cloud>
Joao Cardoso committed
Oct 6, 2025 at 19:27 UTC
3b920aba48c71d9fb3ff90e8aca90ccf29a7b00f
1 file changed
+3
-55
integrations/cloud-notifications/metadata.yaml
+3
-55
@@ -506,6 +506,9 @@
506
- Mutual TLS (recommended): Default authentication mechanism used if no other method is selected
507
- Basic: The client sends a request with an Authorization header that includes a base64-encoded string in the format **username:password**.
508
- Bearer: The client sends a request with an Authorization header that includes a **bearer token**.
509
+ - **Verification**
510
+ - Token: The Token from the latest **Test notification** received on the webhook endpoint.
511
+ - Click on the **Test** button to receive a notification. Token will be embedded in the payload.
512
513
### Webhook service
514
@@ -660,61 +663,6 @@
663
##### Bearer token authentication
664
665
In bearer token authentication, the client sends a request with an Authorization header that includes a bearer token. The server then uses this token to authenticate the client. Bearer tokens are typically generated by an authentication service, and are passed to the client after a successful authentication. If this method is selected, the user can set the token to be used for connecting to the destination service.
663
-
664
- ##### Challenge secret
665
-
666
- To validate that you have ownership of the web application that will receive the webhook events, Netdata is using a challenge response check mechanism.
667
-
668
- This mechanism works as follows:
669
-
670
- - The challenge secret parameter that you provide is a shared secret between only you and Netdata.
671
- - On your request for creating a new Webhook integration, Netdata will make a GET request to the URL of the webhook, adding a query parameter `crc_token`, consisting of a random string.
672
- - You will receive this request on your application and it must construct an encrypted response, consisting of a base64-encoded HMAC SHA-256 hash created from the crc_token and the shared secret. The response will be in the format:
673
-
674
- ```json
675
- {
676
- "response_token": "sha256=9GKoHJYmcHIkhD+C182QWN79YBd+D+Vkj4snmZrfNi4="
677
- }
678
- ```
679
-
680
- - Netdata will compare your application's response with the hash that it will generate using the challenge secret, and if they are the same, the integration creation will succeed.
681
-
682
- Netdata does this validation every time you update your integration configuration.
683
-
684
- - Response requirements:
685
- - A base64 encoded HMAC SHA-256 hash created from the crc_token and the shared secret.
686
- - Valid response_token and JSON format.
687
- - Latency less than 5 seconds.
688
- - 200 HTTP response code.
689
-
690
- **Example response token generation in Python:**
691
-
692
- Here you can see how to define a handler for a Flask application in python 3:
693
-
694
- ```python
695
- import base64
696
- import hashlib
697
- import hmac
698
- import json
699
-
700
- key ='YOUR_CHALLENGE_SECRET'
701
-
702
- @app.route('/webhooks/netdata')
703
- def webhook_challenge():
704
- token = request.args.get('crc_token').encode('ascii')
705
-
706
- # creates HMAC SHA-256 hash from incomming token and your consumer secret
707
- sha256_hash_digest = hmac.new(key.encode(),
708
- msg=token,
709
- digestmod=hashlib.sha256).digest()
710
-
711
- # construct response data with base64 encoded hash
712
- response = {
713
- 'response_token': 'sha256=' + base64.b64encode(sha256_hash_digest).decode('ascii')
714
- }
715
-
716
- # returns properly formatted json response
717
- return json.dumps(response)
666
```
667
668
- id: "notify-cloud-ilert"