Creating and Using Webhooks
CloudShare enables you to configure application webhook events directly from the Integration Hub.
A webhook is a web-based message that is sent from one application (or platform) to another. A webhook message is sent to a predefined, third-party URL when a specific event occurs in the source application, delivering real-time information about that event to the destination application.
After you configure a webhook, it is triggered automatically whenever targeted events occur.
Using webhooks enables you to build any number of scenarios where CloudShare communicates directly with a chosen application when the covered activity takes place. Webhooks do not require that you manually monitor CloudShare, execute external scripts, or manage complex APIs.
Some examples of webhooks include:
-
Sending an email notification when a CloudShare event occurs
-
Posting data that starts an activity in another application
-
Triggering a process via services like Zapier, Tray.io, as well as Integration Platform as a Service (iPaaS) vendors
When you create a webhook in the Integration Hub, CloudShare does all of the required background work: collecting key data from one or more targeted events, preparing the webhook and its payload, and sending it to subscribing application.
To help protect the privacy and security of your data, a CloudShare webhook always attaches a secret key (generated at the account level), which can be optionally used by a subscribing application to authenticate the source of the webhook message. For more details, click here.
For a list of CloudShare events that are currently supported with webhooks, together with their payload details, click here.
Only an Account Manager is able to create webhooks for their CloudShare account.
Before creating a CloudShare webhook, first go to your destination application and prepare the URL that CloudShare will use. Your URL endpoint must be using a valid TLS certificate. You will use this URL to create the webhook. To see an example of this activity and a common use case, click here. Note that you cannot add information to webhooks, including headers. You can, however, choose the endpoint URL.
-
From the main menu, click Integrations. The Integrations page will be displayed, showing all the integration modules available for your account.
-
Click the Webhooks module. The Webhooks configuration panel will appear on the right side of the page, showing the Webhooks List of all current Webhooks configured for the account.
-
Click Add a Webhook. The Create Webhook dialog will be displayed:
-
Enter a Name for the new webhook.
-
From the Project dropdown list, select the Project that will be associated with this webhook. The webhook will only be triggered when one or more events occur in this Project.
-
Enter or paste the URL for your destination application. This is the URL that CloudShare will send when the webhook is triggered. The URL endpoint must be using a valid TLS certificate. An example URL can be found here.
-
Optionally, enter a brief Description for the new webhook.
-
In the Events section of the dialog, activate the checkbox next to each CloudShare event that will trigger sending your new webhook.
-
Click Save. The new webhook will be stored, and the Create a Webhook dialog will close.
The new webhook will now be shown in the Webhooks List for the account.
Only users with Account Manager or Project Manager roles can view the webhooks that are configured for an account.
-
From the main menu, click Integrations. The Integrations page will be displayed.
-
Click the Webhooks module. The Webhooks List is displayed, showing all Webhooks currently configured for the account.
-
To view and edit a specific webhook, in its lower right corner, click on the ellipsis
...menu and then click Edit. The webhook details panel will appear. -
Make the desired changes to the selected webhook. Any updates to a webhook are saved automatically.
-
When you are finished, in the upper left corner of the details panel, click Webhooks List to return to the full webhooks list.
A CloudShare webhook is always sent with a secret key to authenticate its source. (This key is created and maintained at the account level by the Account Manager.) Using the shared secret is optional. The secret key cannot be changed or regenerated.
When using a secret key in your integration, you must provide the key to the subscribing application. To copy the shared secret, on the right side of the Secret text box for the webhook, click the Copy icon:
The key will be copied to the clipboard of your device. You can then paste it where needed (for example, in the authentication code that will be used by the destination application).
Whenever a webhook is triggered, CloudShare always includes the secret key in the x-cloudshare-signature setting of the message header:
Only an Account Manager can delete a webhook from their CloudShare account.
-
From the Webhooks List, locate the webhook your want to delete.
-
In the lower right corner of the webhook, click on the ellipsis
...menu and then click Delete.Alternatively, if webhook details are currently being edited, at the top of the panel, click Delete.
A confirmation message will be displayed.
-
Click OK. The selected webhook will be removed from the account.
You can use a webhook to send an email message to a designated recipient when a specified CloudShare event occurs. For example, a webhook can notify a Project Manager that an active environment in their Project has just been suspended.
A typical webhook requires setup at two locations:
-
in the CloudShare application, where our targeted event occurs; and
-
in the destination application, where the information about our targeted event is going to be used.
Before a webhook can be created in CloudShare we need to configure parameters in the destination application, so that it will know what to do with the webhook message when it is received.
For our example we'll use the tray.io platform as our destination application. Webhook configuration will be similar when using service platforms like Zapier, automate.io and other Integration Platform as a Service (iPaaS) vendors
-
In the tray.io account, create a Connector workflow that uses a webhook to format and send email, and then copy its public URL:
Tip
To configure webhook source authentication using a shared secret, you'll need to add a tray.io crypto-helper to the workflow.
-
In CloudShare, create a new webhook (or edit an existing one), assign it to the relevant Project, and paste the tray.io public URL into the dialog's URL field:
-
Select the CloudShare event that will trigger the webhook. For our example, we'll chose environment.suspended.
-
After the webhook is saved, whenever an environment in the Project is suspended, CloudShare will execute the tray.io URL to send an email. For example:
CloudShare currently supports the creation of detailed webhooks for the following activities. Note that the body of the message includes Event, CreatedAt, CreatedById, CreatedByEmail, Attempt and Payload. POST is the method used to send the webhook. Payload Data represents the keys of the payload in the response body.
|
Events |
Description |
Payload Data (String) |
|---|---|---|
|
Environment Created Environment Suspended Environment Resumed Environment Deleted Environment Extended Environment Archived |
Triggers the relevant key below whenever its event occurs in a targeted Project:
|
|
|
Class Created Class Ended |
Triggers the relevant key below whenever its event occurs in a targeted Project:
|
|
|
Student Enrolled |
Occurs when the student is added to the list of Users for a Class in a targeted Project. Triggers the following key:
|
|
|
Student Invited |
Occurs when an email invitation is sent to a student. |
|
|
Student |
An event that represents each time a student joins a training. |
|
|
Student Request Assistance Student Request Resolved |
Occurs when a student requests assistance in a targeted Project. Triggers the following key:
|
|
Comments
0 comments
Please sign in to leave a comment.