Webhooks

Working With CloudShare 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.

Note: Only Account Managers have the necessary permissions to manage webhooks.

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 or 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 applications.

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. 

See the list of CloudShare events that are currently supported with webhooks, together with their payload details.

Creating and Managing Webhooks

Adding Webhooks

Before creating a CloudShare webhook, first go to your destination application and prepare the URL that CloudShare will use. Your URL endpoint must use a valid TLS certificate. You will use this URL to create the webhook. 
Note that you cannot add information to webhooks, including headers. You can, however, choose the endpoint URL.

1. From the main menu, click Integrations. The Integrations page will be displayed, showing all the integration modules available for your account. Note that you may need to request access to your selected integration module from your CloudShare Customer Success representative.
2. Click the Webhooks module. The webhooks configuration panel will appear on the right side of the page.
3. Click Add a Webhook. The Create Webhook dialog will be displayed:
4. Enter a Name for the new webhook.
5. From the Project drop-down 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.
6. 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 use a valid TLS certificate.
7. Optionally, enter a brief Description for the new webhook.
8. In the Events section of the dialog, activate the checkbox next to each CloudShare event that will trigger sending your new webhook.
9. 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.

Viewing and Editing a Webhook

Note: Only users with Account Manager or Project Manager roles can view the webhooks that are configured for an account.

1. From the main menu, click Integrations. The Integrations page will be displayed.
2. Click the Webhooks module. The webhooks list is displayed, showing all webhooks currently configured for the account.
3. 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.
4. Make the desired changes to the selected webhook. Any updates to a webhook are saved automatically.
5. When you are finished, in the upper left corner of the details panel, click Webhooks List to return to the full webhooks list.

Using the Webhook Shared Secret

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. 

The string in the x-cloudshare-signature header is calculated by the content of the webhook and the secret key. When the webhook is received, you can calculate it the same way and get the same header’s value, using the HMAC-SHA256 base64 output format (refer to this online tool as an example: Free HMAC-SHA256 Online Generator Tool | Devglan). If both strings are the same, it means that this webhook came from us.

Deleting a Webhook

Note: Only an Account Manager can delete a webhook from their CloudShare account.

1. From the webhooks list, locate the webhook you want to delete.
2. 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.
3. Click OK. The selected webhook will be removed from the account.

Example Webhook Use Case and URL

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

1. In the tray.io account, create a Connector workflow that uses a webhook to format and send email, and then copy its public URL:
   
   
   
   To configure webhook source authentication using a shared secret, you'll need to add a tray.io crypto-helper to the workflow.
2. 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.
3. Select the CloudShare event that will trigger the webhook. For our example, we'll choose environment.suspended.
4. 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:
   
   

‘Classic’ Version Webhooks Events

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.