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: