Skip to content

Commit e5bc36d

Browse files
shwstpprshwstppr
authored
feature: webhooks (#385)
* feature: webhooks Documentation for apache/cloudstack#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]>
1 parent 3626f28 commit e5bc36d

File tree

5 files changed

+205
-0
lines changed

5 files changed

+205
-0
lines changed

‎source/_static/images/create-webhook.png‎

40.2 KB
Loading

‎source/_static/images/webhook-deliveries.png‎

141 KB
Loading

‎source/_static/images/webhooks.png‎

8.99 KB
Loading

‎source/adminguide/events.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -366,3 +366,9 @@ Procedure
366366
date.
367367

368368
#. Click OK.
369+
370+
371+
Webhooks
372+
--------
373+
374+
.. include:: events/webhooks.rst

‎source/adminguide/events/webhooks.rst‎

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
.. Licensed to the Apache Software Foundation (ASF) under one
2+
or more contributor license agreements. See the NOTICE file
3+
distributed with this work for additional information#
4+
regarding copyright ownership. The ASF licenses this file
5+
to you under the Apache License, Version 2.0 (the
6+
"License"); you may not use this file except in compliance
7+
with the License. You may obtain a copy of the License at
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
Unless required by applicable law or agreed to in writing,
10+
software distributed under the License is distributed on an
11+
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
12+
KIND, either express or implied. See the License for the
13+
specific language governing permissions and limitations
14+
under the License.
15+
16+
17+
Webhooks allow external services to be notified when certain events happen.
18+
CloudStack allows provisioning webhooks for all account roles and for various
19+
scopes.
20+
This allows users to consume event notifications without any external services
21+
such as an event streaming platforms.
22+
23+
Webhooks can be managed using both API and UI. CloudStack provides following
24+
APIs for webhhoks:
25+
26+
.. cssclass:: table-striped table-bordered table-hover
27+
28+
====================== ===========================
29+
API Description
30+
====================== ===========================
31+
createWebhook Creates a Webhook
32+
listWebhooks Lists Webhooks
33+
updateWebhook Updates a Webhook
34+
deleteWebhook Deletes a Webhook
35+
listWebhookDeliveries Lists Webhook deliveries
36+
deleteWebhookDelivery Deletes Webhook delivery(s)
37+
executeWebhookDelivery Executes a Webhook delivery
38+
====================== ===========================
39+
40+
In the UI, webhooks can be managed under *Tools > Webhhooks* menu.
41+
42+
|webhooks.png|
43+
44+
45+
Creating a webhook
46+
~~~~~~~~~~~~~~~~~~
47+
48+
Any CloudStack user having createWebhook API access can create a new webhook
49+
for the event notifications.
50+
51+
To create a webhook:
52+
53+
#. Log in to the CloudStack UI.
54+
55+
#. In the left navigation bar, click Tools and choose Webhooks.
56+
57+
#. Click Create Webhook.
58+
59+
#. In the dialog, make the following choices:
60+
61+
- **Name**. Any desired name for the webhook.
62+
63+
- **Description**. A short description of the webhook.
64+
65+
- **Scope**. (Available only for ROOT admins or domain admins). Scope
66+
of the webhook. The value can be Local, Domain or Global.
67+
Local - only events associated with the owner account will be notified.
68+
Domain - events associated with domain will be notified.
69+
Global - all events will be notified. This is available only for ROOT
70+
admin account.
71+
For a normal user account, webhooks can be created with Local scope
72+
only.
73+
74+
- **Domain**. An optional domain for the Webhook. If the account parameter
75+
is used, domain must also be used.
76+
77+
- **Account**. An optional account for the webhook. Must be used with
78+
domain.
79+
80+
- **Payload URL**. The payload URL of the Webhook. All events for the
81+
webhook will posted on this URL.
82+
83+
- **SSL Verification**. An otional parameter to specify whether the HTTP
84+
POST requests for event notications must be sent with strict SSL
85+
verification request when a HTTPS payload URL is used.
86+
87+
- **Secret Key**. An option secret key parameter which can be used to sign
88+
the HTTP POST requests for event notifications with HMAC.
89+
90+
- **Enabled**. To specify whether the webhook be created with enabled or
91+
disabled state
92+
93+
|create-webhook.png|
94+
95+
96+
Working with webhook deliveries
97+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
98+
99+
CloudStack attempts webhook deliveries using a thread pool with given retries.
100+
The following global configuration can be used to configure thread pool size
101+
for deliveries:
102+
103+
- **webhook.delivery.thread.pool.size**: Size of the thread pool for webhook
104+
deliveries.
105+
106+
107+
Also, the number attempts for a particular event notification and the timeout
108+
for one particular attempt can be configured using the following domain-level
109+
configurations:
110+
111+
- **webhook.delivery.retries**: Number of tries to be made for a webhook
112+
delivery.
113+
114+
- **webhook.delivery.timeout**: Wait timeout (in seconds) for a webhook
115+
delivery attempt.
116+
117+
.. note::
118+
The onus of dealing with the duplicate event deliveries lies with the payload
119+
server or application. During delivery, when the server doesn't respond in a
120+
timely manner or returns a failure CloudStack will re-attempt the delivery of
121+
the event, based on the above global settings, irrespective of the fact whether
122+
the server already received the event in any previous attempts.
123+
124+
125+
CloudStack allows retrieving recent deliveries for a webhook with details such
126+
as event, headers, payload, respose, success, duration, etc.
127+
In the UI, these can be accessed under Recent deliveries tab in the Webhook
128+
detail view.
129+
The user can redeliver an existing delivery. To check the working of the
130+
webhook consumer test deliveries can made. Test deliveries are not recorded
131+
by CloudStack.
132+
133+
|webhook-deliveries.png|
134+
135+
The administrator can configure storage of webhook deliveries using the
136+
following global configurations:
137+
138+
- **webhook.deliveries.limit**: Limit for number of deliveries to keep
139+
in DB per webhook. Default value is 10.
140+
141+
- **webhook.deliveries.cleanup.interval**: Interval (in seconds) for
142+
cleaning up webhook deliveries. Default value is 3600 or 1 hour.
143+
144+
- **webhook.deliveries.cleanup.initial.delay**: Initial delay (in seconds)
145+
for webhook deliveries cleanup task. Default value is 180.
146+
147+
Based on the above configurations CloudStack will purge older deliveries in
148+
the database using a repeatedly running task.
149+
150+
For a webhook delivery, CloudStack sends a HTTP POST request with event data
151+
as the payload. The following custom headers are sent with the request:
152+
153+
- **X-CS-Event-ID**. Event ID for which the webhook delivery is made.
154+
155+
- **X-CS-Event**. Event for for which the webhook delivery is made.
156+
157+
- **User-Agent**. In the format - *CS-Hookshot/<ACCOUNT_ID>*. Here
158+
ACCOUNT_ID is the ID of the account which trigerred the event.
159+
160+
- **X-CS-Signature**. HMAC SHA256 signature created using the webhook
161+
secret key and the delivery payload. It is sent only when secret key
162+
is specified for the webhook.
163+
164+
165+
Working with HTTPS webhook payload URL with self-signed certificate
166+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
167+
168+
#. Generate a self signed certificate for the server, make sure to mention the IP address of the server when it prompts.
169+
170+
.. parsed-literal::
171+
172+
openssl req -x509 -newkey rsa:4096 -nodes -out cert.pem -keyout key.pem -days 365
173+
174+
#. Copy the genereated cert.pem to the management server(s).
175+
176+
#. Import the certificate for JDK on the management server(s)
177+
178+
.. parsed-literal::
179+
180+
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
181+
182+
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
183+
184+
4. Test the webhook.
185+
186+
187+
188+
.. Images
189+
190+
191+
.. |webhooks.png| image:: /_static/images/webhooks.png
192+
.. |create-webhook.png| image:: /_static/images/create-webhook.png
193+
.. |webhook-deliveries.png| image:: /_static/images/webhook-deliveries.png
194+
195+
196+
197+
198+
199+

0 commit comments

Comments
 (0)