This is an automated email from the ASF dual-hosted git repository.
rohit pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/cloudstack-documentation.git
The following commit(s) were added to refs/heads/main by this push:
new e5bc36d feature: webhooks (#385)
e5bc36d is described below
commit e5bc36d2a3087c33a5b93437aae638646d78e22f
Author: Abhishek Kumar <[email protected]>
AuthorDate: Mon Jun 10 10:40:44 2024 +0530
feature: webhooks (#385)
* feature: webhooks
Documentation for https://github.com/apache/cloudstack/pull/8674
* changes
Signed-off-by: Abhishek Kumar <[email protected]>
* changes
Signed-off-by: Abhishek Kumar <[email protected]>
* changes
Signed-off-by: Abhishek Kumar <[email protected]>
* Update source/adminguide/events/webhooks.rst
* note regarding duplicate event deliveries
Signed-off-by: Abhishek Kumar <[email protected]>
* note on self-signed https payload url
Signed-off-by: Abhishek Kumar <[email protected]>
---------
Signed-off-by: Abhishek Kumar <[email protected]>
---
source/_static/images/create-webhook.png | Bin 0 -> 41163 bytes
source/_static/images/webhook-deliveries.png | Bin 0 -> 144842 bytes
source/_static/images/webhooks.png | Bin 0 -> 9203 bytes
source/adminguide/events.rst | 6 +
source/adminguide/events/webhooks.rst | 199 +++++++++++++++++++++++++++
5 files changed, 205 insertions(+)
diff --git a/source/_static/images/create-webhook.png
b/source/_static/images/create-webhook.png
new file mode 100644
index 0000000..f1f6286
Binary files /dev/null and b/source/_static/images/create-webhook.png differ
diff --git a/source/_static/images/webhook-deliveries.png
b/source/_static/images/webhook-deliveries.png
new file mode 100644
index 0000000..bb49ffb
Binary files /dev/null and b/source/_static/images/webhook-deliveries.png differ
diff --git a/source/_static/images/webhooks.png
b/source/_static/images/webhooks.png
new file mode 100644
index 0000000..b8e9ed5
Binary files /dev/null and b/source/_static/images/webhooks.png differ
diff --git a/source/adminguide/events.rst b/source/adminguide/events.rst
index 7766973..42402d8 100644
--- a/source/adminguide/events.rst
+++ b/source/adminguide/events.rst
@@ -366,3 +366,9 @@ Procedure
date.
#. Click OK.
+
+
+Webhooks
+--------
+
+.. include:: events/webhooks.rst
diff --git a/source/adminguide/events/webhooks.rst
b/source/adminguide/events/webhooks.rst
new file mode 100644
index 0000000..15e57cb
--- /dev/null
+++ b/source/adminguide/events/webhooks.rst
@@ -0,0 +1,199 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information#
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+
+Webhooks allow external services to be notified when certain events happen.
+CloudStack allows provisioning webhooks for all account roles and for various
+scopes.
+This allows users to consume event notifications without any external services
+such as an event streaming platforms.
+
+Webhooks can be managed using both API and UI. CloudStack provides following
+APIs for webhhoks:
+
+ .. cssclass:: table-striped table-bordered table-hover
+
+ ====================== ===========================
+ API Description
+ ====================== ===========================
+ createWebhook Creates a Webhook
+ listWebhooks Lists Webhooks
+ updateWebhook Updates a Webhook
+ deleteWebhook Deletes a Webhook
+ listWebhookDeliveries Lists Webhook deliveries
+ deleteWebhookDelivery Deletes Webhook delivery(s)
+ executeWebhookDelivery Executes a Webhook delivery
+ ====================== ===========================
+
+In the UI, webhooks can be managed under *Tools > Webhhooks* menu.
+
+ |webhooks.png|
+
+
+Creating a webhook
+~~~~~~~~~~~~~~~~~~
+
+Any CloudStack user having createWebhook API access can create a new webhook
+for the event notifications.
+
+To create a webhook:
+
+#. Log in to the CloudStack UI.
+
+#. In the left navigation bar, click Tools and choose Webhooks.
+
+#. Click Create Webhook.
+
+#. In the dialog, make the following choices:
+
+ - **Name**. Any desired name for the webhook.
+
+ - **Description**. A short description of the webhook.
+
+ - **Scope**. (Available only for ROOT admins or domain admins). Scope
+ of the webhook. The value can be Local, Domain or Global.
+ Local - only events associated with the owner account will be notified.
+ Domain - events associated with domain will be notified.
+ Global - all events will be notified. This is available only for ROOT
+ admin account.
+ For a normal user account, webhooks can be created with Local scope
+ only.
+
+ - **Domain**. An optional domain for the Webhook. If the account parameter
+ is used, domain must also be used.
+
+ - **Account**. An optional account for the webhook. Must be used with
+ domain.
+
+ - **Payload URL**. The payload URL of the Webhook. All events for the
+ webhook will posted on this URL.
+
+ - **SSL Verification**. An otional parameter to specify whether the HTTP
+ POST requests for event notications must be sent with strict SSL
+ verification request when a HTTPS payload URL is used.
+
+ - **Secret Key**. An option secret key parameter which can be used to sign
+ the HTTP POST requests for event notifications with HMAC.
+
+ - **Enabled**. To specify whether the webhook be created with enabled or
+ disabled state
+
+ |create-webhook.png|
+
+
+Working with webhook deliveries
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+CloudStack attempts webhook deliveries using a thread pool with given retries.
+The following global configuration can be used to configure thread pool size
+for deliveries:
+
+ - **webhook.delivery.thread.pool.size**: Size of the thread pool for webhook
+ deliveries.
+
+
+Also, the number attempts for a particular event notification and the timeout
+for one particular attempt can be configured using the following domain-level
+configurations:
+
+ - **webhook.delivery.retries**: Number of tries to be made for a webhook
+ delivery.
+
+ - **webhook.delivery.timeout**: Wait timeout (in seconds) for a webhook
+ delivery attempt.
+
+.. note::
+ The onus of dealing with the duplicate event deliveries lies with the
payload
+ server or application. During delivery, when the server doesn't respond in a
+ timely manner or returns a failure CloudStack will re-attempt the delivery
of
+ the event, based on the above global settings, irrespective of the fact
whether
+ the server already received the event in any previous attempts.
+
+
+CloudStack allows retrieving recent deliveries for a webhook with details such
+as event, headers, payload, respose, success, duration, etc.
+In the UI, these can be accessed under Recent deliveries tab in the Webhook
+detail view.
+The user can redeliver an existing delivery. To check the working of the
+webhook consumer test deliveries can made. Test deliveries are not recorded
+by CloudStack.
+
+ |webhook-deliveries.png|
+
+The administrator can configure storage of webhook deliveries using the
+following global configurations:
+
+ - **webhook.deliveries.limit**: Limit for number of deliveries to keep
+ in DB per webhook. Default value is 10.
+
+ - **webhook.deliveries.cleanup.interval**: Interval (in seconds) for
+ cleaning up webhook deliveries. Default value is 3600 or 1 hour.
+
+ - **webhook.deliveries.cleanup.initial.delay**: Initial delay (in seconds)
+ for webhook deliveries cleanup task. Default value is 180.
+
+Based on the above configurations CloudStack will purge older deliveries in
+the database using a repeatedly running task.
+
+For a webhook delivery, CloudStack sends a HTTP POST request with event data
+as the payload. The following custom headers are sent with the request:
+
+ - **X-CS-Event-ID**. Event ID for which the webhook delivery is made.
+
+ - **X-CS-Event**. Event for for which the webhook delivery is made.
+
+ - **User-Agent**. In the format - *CS-Hookshot/<ACCOUNT_ID>*. Here
+ ACCOUNT_ID is the ID of the account which trigerred the event.
+
+ - **X-CS-Signature**. HMAC SHA256 signature created using the webhook
+ secret key and the delivery payload. It is sent only when secret key
+ is specified for the webhook.
+
+
+Working with HTTPS webhook payload URL with self-signed certificate
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+#. Generate a self signed certificate for the server, make sure to mention the
IP address of the server when it prompts.
+
+ .. parsed-literal::
+
+ openssl req -x509 -newkey rsa:4096 -nodes -out cert.pem -keyout key.pem
-days 365
+
+#. Copy the genereated cert.pem to the management server(s).
+
+#. Import the certificate for JDK on the management server(s)
+
+ .. parsed-literal::
+
+ cp
/etc/java/java-17-openjdk/java-17-openjdk-17.0.10.0.7-2.0.1.el8.x86_64/lib/security/cacerts
/etc/java/java-17-openjdk/java-17-openjdk-17.0.10.0.7-2.0.1.el8.x86_64/lib/security/jssecacerts
+
+ keytool -importcert -file /root/kiran/cert.pem -alias webhook -keystore
/etc/java/java-17-openjdk/java-17-openjdk-17.0.10.0.7-2.0.1.el8.x86_64/lib/security/jssecacerts
-storepass changeit
+
+4. Test the webhook.
+
+
+
+.. Images
+
+
+.. |webhooks.png| image:: /_static/images/webhooks.png
+.. |create-webhook.png| image:: /_static/images/create-webhook.png
+.. |webhook-deliveries.png| image:: /_static/images/webhook-deliveries.png
+
+
+
+
+
+
