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:

1. Request your authentication token .
2. Create the webhook configuration .
3. Receive webhook alerts .
4. Manage your webhook configuration .

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:

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:

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:

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:

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"
    }
}

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.