Managing Webhooks via API

In this section, we’ll guide you through the process of managing webhooks using Circularo’s API. You’ll find detailed instructions on how to create, view, and delete webhooks.

To manage webhooks, you need to be either a team admin or a global admin.

Create new webhook

Endpoint:

JS

POST /webhooks?token=:authenticationToken

Create webhook from global admin account

Global admins can create webhooks for the entire tenant or for a specific team.

Tenant-Wide Webhook: To create a webhook that works for all documents tenant-wide, send a request like this:

JS

POST /webhooks?token=:authenticationToken

{
  "type": "tenant",
  "callbackUrl": "https://www.valid.url/callback",
  "hmacSecret": "optionalHMAC"
}

Team-Wide Webhook: To create a webhook that works for team documents only, send a request like this:

JS

POST /webhooks?token=:authenticationToken

{
  "type": "team",
  "name": "teamName",
  "callbackUrl": "https://www.valid.url/callback",
  "hmacSecret": "optionalHMAC"
}

Create webhook from team admin account

Team admins can create webhooks for their specific team.

Team-Wide Webhook: To create webhook that works for team documents only, send a request like this:

JS

POST /webhooks?token=:authenticationToken

{
  "type": "team",
  "callbackUrl": "https://www.valid.url/callback",
  "hmacSecret": "optionalHMAC"
}

Response example

JS

{
  "id": "aX5dsEEd2eDfaJz8R",
  "creator": "teamAdminUser",
  "createDate": "2022-06-24T13:05:10.500Z",
  "type": "team",
  "name": "myTeam",
  "callbackUrl": "https://www.valid.url/callback",
  "hmacSecret": "optionalHMAC"
}

View existing webhooks

Endpoint

JS

GET /webhooks?token=:authenticationToken

This allows you to see all existing webhooks. Global admin can see all existing webhooks, while team admins see only their team’s webhooks.

Response

JS

{
  "results": [
    {
      "id": "aX5dsEEd2eDfaJz8R",
      "creator": "teamAdminUser",
      "createDate": "2024-06-01T13:10:10.500Z",
      "type": "team",
      "name": "myTeam",
      "callbackUrl": "https://www.valid.url/callback",
      "hmacSecret": "optionalHMAC"
    }
  ],
  "total": 1
}

Delete webhook

Endpoint

JS

DELETE /webhooks/:id?token=:authenticationToken

This endpoint allows you to delete a webhook. Global admins can delete any webhook, while team admins can delete only their team’s webhooks.