Sellers can integrate with Cloudmore using webhooks. When setting up a service in Cloudmore, there are two provisioning options – triggering an email or Cloudmore Service Connector. Cloudmore Service Connector will enable webhooks and end-to-end automation between Cloudmore and external services.
These webhooks needs to be defined for each service to inform Cloudmore where different events should be sent. API’s can be used to create webhooks based on event types in Cloudmore.
Prerequisite
Before creating a webhook, you need to create a service in the Cloudmore Seller layer with all the products, add-ons, and settings needed for the service.
Process
Once a webhook is setup, an event in Cloudmore triggers a webhook call to the external connector (URL provided in the webhook creation) which will then have to translate it and communicate with an external system to take the correct action.
It may be possible that the data provided in the webhook call will not contain enough information to carry out the appropriate action. In this case it will be be necessary to query additional information from the Cloudmore API. The full process:
- Setup the service
A service will need to be set up along with its product(s), addon(s) if required and published once it’s ready to be published in the Marketplace . - Create the webhook
Webhooks will need to be setup for each action required in the integration. Webhooks that can be created include:- BrokerAddService
A broker in Cloudmore adds the service from the marketplace - BrokerDeleteService
A broker in Cloudmore removes the service from My Services - OrganizationAddService
An organization in Cloudmore adds the service from the E-store - OrganizationDeleteService
An organization in Cloudmore removes the service from My Services - SubscriptionCreated
A subscription is created for an organization - SubscriptionUpdated
A subscription is updated - SubscriptionCancelled
A subscription is marked as cancelled - SubscriptionDeleted
A subscription is deleted - ExternalAdminCreated
An external admin for the service is created in Cloudmore - ExternalAdminDeleted
An external admin for the service is deleted in Cloudmore - UserAttachedToSubscription
A user is attached to a subscription in Cloudmore - UserDetachedFromSubscription
A user is removed from a subscription in Cloudmore.
- BrokerAddService
- Receiving the Webhook call
A payload will be sent for each webhook setup once an action in Cloudmore is performed. - If the payload received does not contain all the information required, use the Cloudmore API to retrieve the necessary information.
- Perform any action required in the external system that is required for the integration.
- If any information needs to be updated in Cloudmore as a result of the external action, an API call can be done to achieve this. Custom properties are usually used to store external system fields.
API Details
| Webhooks | |||
| Operation | Swagger Description | Method | API |
| Create a Webhook | Creates new webhook for the seller service | POST | /api/sellers/{sellerId}/webhooks |
| Return a Webhook | Returns seller webhook by identifier | GET | /api/sellers/{sellerId}/webhooks/{id} |
| Return all Webhooks | Returns all seller webhooks | GET | /api/sellers/{sellerId}/webhooks |
| Update a Webhook | Updates webhook | PUT | /api/sellers/{sellerId}/webhooks/{id} |
| Delete a Webhook | Deletes webhook | DELETE | /api/sellers/{sellerId}/webhooks/{id} |
Create a Webhook
| Create a Webhook | |
|---|---|
| End Point | /api/sellers/{sellerId}/webhooks |
| HTTP Method | POST |
| Request Body | { "messageToSendType": "OnlyTriggerAction", "basicAuthPassword": "test123", "basicAuthUserName": "test@test.com", "url": "https://webhook.site/e4f9f834-8cc0-40ec-bb75-99bc509a2740", "serviceId": "8806367b-001a-4632-afb4-27a7fad7660c", "triggerEventType": "SubscriptionUpdated", "name": "GoogleWorkspaceSubscriptionUpdated" } |
| Successful Example Response | 204 |
| Error Example Response | 400{ "Url": [ "The Url field is required." ], "ServiceId": [ "The ServiceId field is required." ] } |
Field Definitions
| Field | Description |
| name* | Friendly name of the webhook. |
| messageToSendType | Type of message to send. Possible values: OnlyTriggerAction |
| basicAuthPassword | Basic Authentication Password. |
| basicAuthUserName | Basic Authentication User Name. |
| httpHeader | Specify http header parameters. |
| url* | The URL to send the webhook too. This should be a complete URL with http:// or https://. |
| serviceId* | The Cloudmore uuid of the service. |
| triggerEventType | What event to trigger the webhook on. Possible values: – BrokerAddService A broker in Cloudmore adds the service from the marketplace – BrokerDeleteService A broker in Cloudmore removes the service from My Services – OrganizationAddService An organization in Cloudmore adds the service from the E-store – OrganizationDeleteService An organization in Cloudmore removes the service from My Services – SubscriptionCreated A subscription is created for an organization – SubscriptionUpdated A subscription is updated – SubscriptionCancelled A subscription is marked as canceled – SubscriptionDeleted A subscription is deleted – ExternalAdminCreated An external admin for the service is created in Cloudmore – ExternalAdminDeleted An external admin for the service is deleted in Cloudmore – UserAttachedToSubscription A user is attached to a subscription in Cloudmore – UserDetachedFromSubscription A user is removed from a subscription in Cloudmore |
Receiving the Webhook call
The connector needs to be set up to receive the webhook call from Cloudmore. The payload of the webhook call will look like this:
| Field | Description | Detailed API Information |
|---|---|---|
| BrokerAddService/BrokerDeleteService/OrganizationAddService/OrganizationDeleteService/SubscriptionCreated/SubscriptionUpdated/SubscriptionCancelled/SubscriptionDeleted | ||
{ "organizationId": "b8bc8c08-1062-40c3-8317-39f09dce6ab8", "organizationName": "ABCD Company", "brokerId": "9230183c-6aeb-412f-9c7b-5a94d3cf82dc", "serviceId": "8806367b-001a-4632-afb4-27a7fad7660c", "brokerServiceId": null, "organizationServiceId": null, "subscriptionId": "86a15bad-10b6-4539-b049-0b9ffa76001f", "parentId": "3d6ad361-fbc9-4bcc-8285-fd8fc77b47f5", "customPropertiesData": { "entitlementId": "" }, "triggerEventType": "SubscriptionUpdated", "serviceOwnerId": "3d6ad361-fbc9-4bcc-8285-fd8fc77b47f5" } | ||
| organizationId | The unique identifier of an organization in Cloudmore. | Manage Organizations |
| organizationName | The name of the organization. | Manage Organizations |
| brokerId | The unique identifier of the broker. | Manage Resellers |
| serviceId | The unique identifier of the service. | Creating a Seller Service |
| brokerServiceId | The unique identifier of the broker service object. Can be ignored. | N/A. |
| organizationServiceId | The unique identifier of the organization service object. Can be ignored. | N/A. |
| subscriptionId | The unique identifier of the subscription. | Manage Subscriptions |
| parentId | The unique identifier of the seller. | N/A. |
| customPropertiesData | The custom property and value if any have been defined. | Custom Properties |
| triggerEventType | The Trigger Event Type that triggered the webhook. | See Field Definitions |
| serviceOwnerId | The unique identifier of the seller. | N/A. |
| UserAttachedToSubscription and UserDetachedFromSubscription | ||
{ "userSubscriptionId": "1be2e8e1-636b-4194-8802-016f53b90319", "userId": "91135c98-5fa6-48c2-9011-b4cb6c165d6b", "externalUserId": null, "serviceId": "8806367b-001a-4632-afb4-27a7fad7660c", "subscriptionId": "f8332a2d-5f47-4090-bd31-382b907eb9ed", "brokerId": "600348ae-6fd2-4c0e-8c85-9e88b30fe321", "organizationId": "7d7e71e5-3c8c-4ade-87eb-9fc8fbc734ea", "organizationName": "ABCD Company", "parentId": "3d6ad361-fbc9-4bcc-8285-fd8fc77b47f5", "customPropertiesData": { "entitlementId": "" }, "triggerEventType": "UserAttachedToSubscription", "serviceOwnerId": "3d6ad361-fbc9-4bcc-8285-fd8fc77b47f5" } | ||
| userSubscriptionId | ||
| userId | The identifier of the user to be assigned to the subscription. | Manage Users |
| externalUserId | The external identifier of the user. | Manage Users |
| organizationId | The unique identifier of an organization in Cloudmore. | Manage Organizations |
| organizationName | The name of the organization. | Manage Organizations |
| brokerId | The unique identifier of the broker. | Manage Resellers |
| serviceId | The unique identifier of the service. | Creating a Seller Service |
| subscriptionId | The unique identifier of the subscription. | Manage Subscriptions |
| parentId | The unique identifier of the seller. | N/A. |
| customPropertiesData | The custom property and value if any have been defined. | Custom Properties |
| triggerEventType | The Trigger Event Type that triggered the webhook. | See Field Definitions |
| serviceOwnerId | The unique identifier of the seller. | N/A. |