What is a webhook

Webhooks enable Coro to send real-time alerts to third-party applications, facilitating automation for critical tasks like billing. These alerts are sent to a specified URL over HTTP. This push mechanism makes webhooks an efficient and responsive way to transmit real-time data between services.

How webhooks work

Webhooks in Coro allow you to automate actions in response to specific events. The workflow involves the following steps:

Event occurrence: A predefined event takes place in Coro. This could be billing-related, such as a subscription being updated or a workspace's user count changing.
Webhook trigger: The event triggers the webhook, prompting Coro to send an HTTP POST request to a predefined URL in the target application.
Data transmission: The POST request contains data related to the event, typically in JSON format.
Processing: The target application receives the request and processes the data, triggering further actions or workflows as required.

Webhook security

To ensure secure communication, Coro includes several headers with each webhook to verify the authenticity of the request and protect the integrity of data being transferred:

X-Coro-Hook-Id: This is a unique, randomly generated identifier for each webhook event. Every time an event occurs that triggers a webhook, Coro assigns a new X-Coro-Hook-Id, ensuring that each event has a unique identifier. This ID is also included in the webhook payload, allowing the receiving system to match the ID in the headers with the one in the payload, confirming consistency. This can also be used for filtering purposes without reading the webhook body.
X-Coro-Hook-Type: This header specifies the type of event that triggered the webhook (such as workspace-createdor subscription-updated). It helps the receiving system to understand what type of action or event occurred within Coro, matching the event data in the payload to the appropriate trigger. This can also be used for filtering purposes without reading the webhook body.
X-Coro-Signature: This is a SHA-256 hash signature that verifies the authenticity of the webhook payload by utilizing Hash-based Message Authentication Code (HMAC). The signature is created using a combination of the X-Coro-Hook-Id and a secret key (provided by the user during webhook configuration). Coro uses this key to hash the X-Coro-Hook-Id, generating the X-Coro-Signature.
Here's how the signature validation works:
1. Coro generates a hash by signing the X-Coro-Hook-Id with the secret key you provided during webhook configuration. This results in the X-Coro-Signature.
2. When you receive the webhook, verify its authenticity by recalculating the signature on your side. You use the same X-Coro-Hook-Id from the webhook and the secret key (which only you and Coro know, and should be stored in a secure location) to recreate the hash. If your calculated hash matches the X-Coro-Signature in the header, you can be confident that the webhook is legitimate and came from Coro.

This layered security model ensures that even if the webhook data were intercepted, it could not be altered or impersonated without access to the secret key used to generate the signature. By validating both the X-Coro-Hook-Id and the X-Coro-Signature, you ensure that the webhook payload has not been tampered with and originates from Coro.

Webhook events

With Coro, you can receive real-time notification and information about the following events:

Event	Trigger
workspace-created	A workspace is created.
workspace-status-updated	A workspace's status is updated, excluding when a workspace is created.
subscription-updated	Changes are made to the workspace subscription.
protected-users-added	New protected users are added.
protected-users-updated	Existing protected users are updated or removed from protection.
protected-users-deleted	Protected users are deleted.
protected-users-count-updated	Protected users are added or deleted.
protected-devices-added	New protected devices are added.
protected-devices-updated	Existing protected devices are updated.
protected-devices-deleted	Protected devices are deleted.
protected-devices-count-updated	Protected devices are added or deleted.

Webhook payload structure

Webhook payloads appear similar to:

{
  "id": "12345",
  "timestamp": "1627670400000",
  "workspaceId": "workspace123",
  "type": "protected-devices-count-updated",
  "data": {
    "protectedCount": 100
  }
}

The following table describes the parameters in the payload:

Parameter	Description	Example
`id`	The unique identifier of the webhook.	12345
`timestamp`	The timestamp of the webhook, in UTC milliseconds.	1627670400000
`workspaceId`	The unique identifier of the workspace to which the webhook applies.	workspace123
`type`	The event which triggered the webhook.	protected-devices-count-updated
`data`	An object containing all additional fields specific to the relevant webhook type.	-
`data > protectedCount`	The new total number of protected devices in the workspace.	100

Every webhook event includes a different data object:

workspace-created:

{
"data": {
  "companyName": "comapny1",
  "displayName": "company1",
  "domain": "company1Workspace.com",
  "type": "child",
  "maxProtectedUsers": "25",
  "notificationLevel": "parent",
  "parentWorkspaceId": "parentWorkspace",
  "adminEmails": "admin2@company1workspace.com",
  "workspaceCreationTime": "1641009600000"
  "subscriptionType": "initial"
  }
}

Parameter	Description	Example
`companyName`	The name of the company for which the workspace is created.	company1
`displayName`	The name displayed for the workspace from the user interface.	company1
`domain`	The workspace domain.	company1Workspace.com
`type`	The type of workspace being created. Options include: `regular` - for individual companies; `channel` - for the MSP parent level; `child` - for MSP customers.	child
`maxProtectedUsers`	The maximum number of users allowed in the workspace.	25
`notificationsLevel`	The workspace admins who will receive notifications. Options include: `none`, `parent`, `all`.	parent
`parentWorkspaceId`	The unique identifier of the parent workspace, if applicable.	parentWorkspace
`adminEmails`	The email addresses of all admins associated with the workspace.	admin2@company1workspace.com
`workspaceCreationTime`	The date the workspace was created, in UNIX format, including milliseconds.	1641009600000
`subscriptionType`	The type of subscription. Options include: initial - a workspace has been created but an onboarding event to trigger the trial state has not yet occurred; trial - an onboarding event has been triggered, such as a cloud app is connected or device is activated; freeze - the trial or subscription has expired; subscription - an admin has started the subscription; archived - the trial or subscription has expired, cloud apps are disconnected, and network settings are cleared;	initial

workspace-status-updated:

{
"data": {
  "subscriptionType": "subscription"
  }
}

Parameter	Description	Example
`subscriptionType`	The type of subscription. Options include: `initial` - a workspace has been created but an onboarding event to trigger the trial state has not yet occurred; `trial` - an onboarding event has been triggered, such as a cloud app is connected or device is activated; `freeze` - the trial or subscription has expired; `subscription` - an admin has started the subscription; `archived` - the trial or subscription has expired, cloud apps are disconnected, and network settings are cleared;	subscription

subscription-updated

{
"data": {
  "bundles": ["CORO_CLASSIC", "ENDPOINT_PROTECTION"]
  "modules": ["CLOUD_SECURITY", "EDR"]
  "addons": ["WIFI_PHISHING"]
  }
}

Parameter	Description	Example
`bundles`	The bundles enabled in the subscription.	CORO_CLASSIC, ENDPOINT_PROTECTION
`modules`	The modules enabled in the subscription.	CLOUD_SECURITY, EDR
`addons`	The add-ons enabled in the subscription.	WIFI_PHISHING

protected-users-added

{
"data": {
  "users": [
    {
      "id": "62ff9653efef4b3ae04ab25e",
      "email": "awiggin@company1.com",
      "name": "Andrew Wiggin",
      "protectedUser": true
      }
    ]
  }
}

Parameter	Description	Example
`users -> id`	The unique identifier of the user.	62ff9653efef4b3ae04ab25e
`users -> email`	The user's email.	awiggin@company1.com
`users -> name`	The user's name.	Andrew Wiggin
`users -> protectedUser`	The protection status of the user. Options include: `true` - protected; `false` - not protected.	true

protected-users-updated

{
"data": {
  "users": [
    {
      "id": "62ff9653efef4b3ae04ab25e",
      "email": "awiggin@company1.com",
      "name": "Andrew Wiggin",
      "protectedUser": false
      }
    ]
  }
}

Parameter	Description	Example
`users -> id`	The unique identifier of the user.	62ff9653efef4b3ae04ab25e
`users -> email`	The user's email.	awiggin@company1.com
`users -> name`	The user's name.	Andrew Wiggin
`users -> protectedUser`	The protection status of the user. Options include: `true` - protected; `false` - not protected.	false

protected-users-deleted
```
{
"data": {
  "users": [
    {
      "id": "62ff9653efef4b3ae04ab25e",
      "email": "awiggin@company1.com"
      }
    ]
  }
}
```
Parameter Description Example
users -> id The unique identifier of the user. 62ff9653efef4b3ae04ab25e
users -> email The user's email. awiggin@company1.com

protected-users-count-updated
```
{
"data": {
  "protectedCount": 100
  }
}
```
Parameter Description Example
protectedCount The new total number of protected users in the workspace. 100

Parameter	Description	Example
`protectedCount`	The new total number of protected users in the workspace.	100

protected-devices-added

{
"data": {
  "devices": [
    {
      "enrollmentCode": "K7AR379123868973",
      "deviceId": "7607033166F17480BA76F075CBAEDCB2E4...",
      "deviceModel": "LENOVO ThinkPad T490s",
      "hostname": "LARYCHYZH6D58",
      "osType": "WINDOWS",
      "osVersion": "10.0.22000",
      "appVersion": "2.0.92.1",
      "activationTime": 1663004585139
      }
    ]
  }
}

Parameter	Description	Example
`enrollmentCode`	Coro's unique enrollment code for a device.	K7AR379123868973
`device Id`	The 16-byte unique number of the device.	7607033166F17480BA76F075CBAEDCB2E4...
`deviceModel`	The device model.	LENOVO ThinkPad T490s
`hostname`	The host name of the device.	LARYCHYZH6D58
`osType`	The operating system installed on the device.	WINDOWS
`osVersion`	The operating system version that is currently installed on the device.	10.0.22000
`appVersion`	The version of Coro that is currently installed on the device.	2.0.92.1
`activationTime`	UNIX timestamp in milliseconds for the time when the device was originally activated in Coro.	1663004585139

protected-devices-updated

{
"data": {
  "users": [
    {
      "enrollmentCode": "K7AR379123868973",
      "hostname": "LARYCHYZH6D58",
      "osVersion": "10.0.22000",
      "appVersion": "2.0.92.1"
      }
    ]
  }
}

Parameter	Description	Example
`enrollmentCode`	Coro's unique enrollment code for a device.	K7AR379123868973
`hostname`	The host name of the device.	LARYCHYZH6D58
`osVersion`	The operating system version that is currently installed on the device.	10.0.22000
`appVersion`	The version of Coro that is currently installed on the device.	2.0.92.1

protected-devices-deleted
```
{
"data": {
  "users": [
    {
      "enrollmentCode": "K7AR379123868973",
      "deviceId": "7607033166F17480BA76F075CBAEDCB2E4..."
      }
    ]
  }
}
```
Parameter Description Example
enrollmentCode Coro's unique enrollment code for a device. K7AR379123868973
device Id The 16-byte unique number of the device. 7607033166F17480BA76F075CBAEDCB2E4...

protected-devices-count-updated
```
{
"data": {
  "protectedCount": 100
  }
}
```
Parameter Description Example
protectedCount The new total number of protected devices in the workspace. 100
Webhook retry logic
If a webhook request fails, up to three additional attemps are made. Coro waits for increasingly longer intervals before each new attempt. If the webhook fails all four times, it is disabled and logged in the activity log.

What is a webhook

How webhooks work

Webhook security

Webhook events

Webhook payload structure

Webhook retry logic

Was this helpful?