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:

  1. 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.
  2. Webhook trigger : The event triggers the webhook, prompting Coro to send an HTTP POST request to a predefined URL in the target application.
  3. Data transmission : The POST request contains data related to the event, typically in JSON format.
  4. 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-created or 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:

Copy
Copied
{
  "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 :
    Copy
    Copied
    {
"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 :
    Copy
    Copied
    {
"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
    Copy
    Copied
    {
"data": {
"bundles": ["CORO_CLASSIC", "ENDPOINT_PROTECTION"]
"modules": ["CLOUD_SECURITY", "EDR"]
"addons": ["WIFI_PHISHING"]
}
}
    Parameter Description Example
    bundles The bundles enabled in the subscription. COROCLASSIC, ENDPOINTPROTECTION
    modules The modules enabled in the subscription. CLOUD_SECURITY, EDR
    addons The add-ons enabled in the subscription. WIFI_PHISHING

  • protected-users-added
    Copy
    Copied
    {
"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
    Copy
    Copied
    {
"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
    Copy
    Copied
    {
"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
    Copy
    Copied
    {
"data": {
"protectedCount": 100
}
}
    Parameter Description Example
    protectedCount The new total number of protected users in the workspace. 100

  • protected-devices-added
    Copy
    Copied
    {
"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
    Copy
    Copied
    {
"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
    Copy
    Copied
    {
"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
    Copy
    Copied
    {
"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.