Create a webhook configuration

Coro provides webhook configuration to enable customers to receive real-time updates when specific events occur in a workspace. These webhooks are ideal for managed service providers (MSPs) to automate billing tasks such as updating invoices or tracking client usage changes. For more information about webhooks, see What are webhooks.

This guide describes how to create a webhook that is triggered when a new workspace is created:

Request your authentication token.
Create the webhook configuration.
Receive webhook alerts.
Manage your webhook configuration.

You can also create webhook configurations from the Coro console. For more information, see Creating and managing webhooks.

Request your authentication token

Make a POST request to the /oauth/token resource endpoint using your Client ID and Client Secret. Each token is valid for 24 hours.

The request should appear similar to:

curl -i -X POST \
  https://api.secure.coro.net/oauth/token \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "2qDgzSrZxnUCs4jqmfdEP5MVkEmA3Uak",
    "client_secret": "9c9Dabz5nQT65LXfYt_61wxb9UssT7tpzTM-gVB4RJZB9gKDf1_TjO6o3eLcBaba",
    "audience": "https://api.secure.coro.net",
    "grant_type": "client_credentials"
  }'

const resp = await fetch(
  `https://api.secure.coro.net/oauth/token`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      client_id: '2qDgzSrZxnUCs4jqmfdEP5MVkEmA3Uak',
      client_secret: '9c9Dabz5nQT65LXfYt_61wxb9UssT7tpzTM-gVB4RJZB9gKDf1_TjO6o3eLcBaba',
      audience: 'https://api.secure.coro.net',
      grant_type: 'client_credentials'
    })
  }
);
const data = await resp.json();
console.log(data);

The following table describes the parameters in the request:

Parameter	Data type	Description	Example	Required
`client_id`	String	The unique identifier for the client. This value is provided by Coro support.	2qDgzSrZxnUCs4jqmfdEP5MVkEmA3Uak	yes
`client_secret`	String	The secret for the client. This value is provided by Coro support.	9c9Dabz5nQT65LXfYt_61wxb9UssT7tpzTM-gVB4RJZB9gKDf1_TjO6o3eLcBaba	yes
`audience`	String	The URL for the Coro API server. Options include: https://api.secure.coro.net, https://api.secure-ca.coro.net, https://api.secure-eu.coro.net	https://api.secure.coro.net	yes
`grant_type`	String	The method by which you want to request a bearer token for authentication. At this time, Coro only supports `client_credentials`.	client_credentials	yes

A successful response appears similar to:

HTTP/1.1 200 OK
Content-Type: application/json
Date: {date}
X-Coro-Trace-Id: {trace-id}
Transfer-Encoding: chunked

{
  "access_token":"TRDNxdkVHYms0R2U1IiwiaWF0IjoxNjTRDNxdkVHYms0R2U1IiwiaWF0IjoxNjTRDNxdkVHYms0R2U1IiwiaWF0IjoxNjTRDNxdkVHYms0R2U1IiwiaWF0IjoxNjTRDNxdkVHYms0R2U1IiwiaWF0IjoxNj.dcukG0cw3eh4jqEMCwxZ2N3mziZ2hpFbv4--VYrXA3Q",
  "token_type":"Bearer",
  "expires_in":86400
  }

The following table describes the parameters in the response:

Parameter	Description	Example
`access_token`	The access token used to access API resources.	TRDNxdkVHYms0R2U1IiwiaWF0IjoxNjTRDNxdkVHYms0R2U1IiwiaWF0IjoxNjTRDNxdkVHYms0R2U1IiwiaWF0IjoxNjTRDNxdkVHYms0R2U1IiwiaWF0IjoxNjTRDNxdkVHYms0R2U1IiwiaWF0IjoxNj.dcukG0cw3eh4jqEMCwxZ2N3mziZ2hpFbv4--VYrXA3Q
`token_type`	The type of token.	Bearer
`expires_in`	The expiration time of the token, in seconds. Each token is valid for 24 hours.	86400

Create the webhook configuration

Create a new webhook configuration. Make a POST request to the /settings/webhooks resource endpoint, and specify the workspace-created trigger.

The request should appear similar to:

curl -i -X POST \
  https://api.secure.coro.net/v1/settings/webhooks \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -H 'Workspace: company1Workspace' \
  -d '{"name": "Billing webhooks",
    "description": "Used for updating QuickBooks",
    "applyToAllDescendants": true,
    "url": "https://www.customer.example/quickbookwebhook",
    "secret": "supersecuresecret",
    "headers":{
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "Content-Type": "application/json"
        },
    "triggers": [
        "workspace-created"
        ],
    "status": "enabled"
    }'

const resp = await fetch(
  `https://api.secure.coro.net/v1/settings/webhooks`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Billing webhooks',
      description: 'Used for updating QuickBooks',
      applyToAllDescendants: true,
      url: 'https://www.customer.example/quickbookwebhook',
      secret: 'supersecuresecret',
      headers: {
        X-Request-ID: 123e4567-e89b-12d3-a456-426614174000
      },
      triggers: [
        'workspace-created'
      ],
      status: 'enabled'
    })
  }
);

const data = await resp.json();
console.log(data);

The following table describes the parameters in the request:

Field	Data type	Description	Example	Required
`Workspace`	String	The workspace identifier, which isolates API requests inside the provided workspace scope.	channelWorkspace	yes
`name`	String	The name of the webhook.	Billing webhooks	No
`description`	String	A longer description, if needed.	Used to update QuickBooks	No
`applyToAllDescendents`	Boolean	If true, webhooks are sent for all descendants of this workspace. This is relevant for channel workspaces.	true	Yes
`url`	String	The URL to which the webhook data will be sent.	https://www.customer.example/quickbookwebhook	Yes
`secret`	String	Used to validate webhooks sent by Coro.	supersecuresecret	Yes
`headers`	Object of strings	A JSON object containing key-value pairs for any additional headers required by the receiving endpoint.	X-Request-ID: 123e4567-e89b-12d3-a456-426614174000	No
`triggers`	Array of strings	A list of events that trigger the webhook.	workspace-created	Yes
`status`	String	The current status of the webhook configuration. Options include enabled and disabled.	enabled	Yes

A successful response appears similar to:

HTTP/1.1 201 Created
Content-Type: application/json
Date: {date}
X-Coro-Trace-Id: {trace-id}
Transfer-Encoding: chunked

{
    "id": "66b204f0c992d50b8b2f984c"
    "name": "Billing webhooks",
    "description": "Used for updating QuickBooks",
    "applyToAllDescendants": true,
    "url": "https://www.customer.example/quickbookwebhook",
    "secret": "supersecuresecret",
    "headers":{
        X-Request-ID: 123e4567-e89b-12d3-a456-426614174000
        },
    "triggers": [
        "workspace-created"
        ],
    "status": "enabled",
    "updated": 0
}

The following table describes the parameters in the response:

Field	Data type	Description	Example
`id`	String	The unique identifier of the webhook configuration.	66b204f0c992d50b8b2f984c
`name`	String	The name of the webhook.	Billing webhooks
`description`	String	A longer description, if needed.	Used to update QuickBooks
`applyToAllDescendents`	Boolean	If true, webhooks are sent for all descendants of this workspace.	true
`url`	String	The URL to which the webhook data will be sent.	https://www.customer.example/quickbookwebhook
`secret`	String	Used to validate webhooks sent by Coro. See Webhook security for more information.	supersecuresecret
`headers`	Object of strings	A JSON object containing key-value pairs for any additional headers required by the receiving endpoint.	X-Request-ID: 123e4567-e89b-12d3-a456-426614174000
`triggers`	Array of strings	A list of events that trigger the webhook.	workspace-created
`status`	String	The current status of the webhook configuration. Options include enabled and disabled.	enabled
`updated`	String	The timestamp of the webhook configuration, in UNIX format including milliseconds.	1709856000000

Receive webhook alerts

Any time a new workspace is created, a webhook alert is sent to the specified URL. The alert appears similar to:

{
  "id": "12345",
  "timestamp": "1627670400000",
  "workspaceId": "workspace123",
  "type": "workspace-created",
  "data": {
    "companyName": "company1",
    "displayName": "company1",
    "domain": "The workspace domain",
    "type": "child",
    "maxProtectedUsers": "25",
    "notificationLevel": "parent",
    "parentWorkspaceId": "parentWorkspace",
    "adminEmails": "admin2@company1workspace.com",
    "workspaceCreationTime": "1641009600000"
    "subscriptionType": "initial"
    }
}

Field	Data type	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.	workspace-created
`data > companyName`	string	The name of the company for which the workspace is created.	company1
`data > displayName`	string	The name displayed for the workspace from the user interface.	company1
`data > domain`	string	The workspace domain.	company1Workspace.com
`data > type`	string	The type of workspace being created. Options include: `regular` - for individual companies; `channel` - for the MSP parent level; `child` - for MSP customers.	child
`data > maxProtectedUsers`	string	The maximum number of users allowed in the workspace.	25
`data > notificationLevel`	string	The admin users who will receive notifications. Options include: `none`, `parent`, `all`.	parent
`data > parentworkspaceId`	string	The unique identifier of the parent workspace, if applicable.	parentWorkspace
`data > adminEmails`	string	The email addresses of all admin users associated with the workspace.	admin2@company1workspace.com
`data > workspaceCreationTime`	string	The date the workspace was created, in UNIX format, including milliseconds.	1641009600000
`data > subscriptionType`	string	The type of subscription for the workspace.	initial

Manage your webhook configuration

After creating a webhook configuration, you can view, update, or delete the configuration with GET, PUT, or DELETE requests to the /settings/webhooks/{id} resource endpoint. For more information about these calls, see the Coro API reference.

Create a webhook configuration

Request your authentication token

Create the webhook configuration

Receive webhook alerts

Manage your webhook configuration

Was this helpful?