Introduction to the Activity API 

Start with our Core API docs for an introduction to the Kloudless API and more information on connecting user accounts and performing API requests.

Once an account is connected to your application, your application can perform API requests to the Activity API endpoints listed below.

Overview

The Kloudless Activity API helps monitor accounts using a variety of service-specific implementations to be aware of activity occurring within each account.

The services that provide activity for each API category are listed below.

Storage Activity

File-system activity data is available for the following services:

  • alfresco

  • alfresco_cloud

  • box

  • cmis

  • cq5

  • dropbox

  • dynamics

  • egnyte

  • evernote

  • gdrive

    • By default, Kloudless does not monitor Team Drives’ activity for Google Drive non-admin accounts. However, up to 4 team drives can be added to the watch list by updating the account’s monitor_team_drives attribute. See the account import and account update docs for more information.
  • hubspot

  • jive

  • onedrivebiz

  • s3

  • salesforce

    • Tracks Chatter files, Libraries, Documents and Attachments only.
  • sharefile

  • sharepoint

    • Tracks only the primary site collection’s Document Library in non-admin accounts.
    • Administrator accounts that connected through the admin OAuth flow with org-wide data access will have all its site collections activity tracked.
  • skydrive

  • smb

  • webdav

  • slack

    • Tracks Slack file, message, and conversation activity that the account has visibility into.
    • Org-wide Slack Enterprise Grid activity available in Slack Audit Logs API can be tracked with Audit activity.
  • autodesk

    • Due to limitations with Autodesk Webhooks API, Autodesk activity for each account is only tracked for one application at a time across all environments.

CRM Activity

CRM activity data is available for the following services:

  • salesforce

    • Tracks all custom objects (up to the maximum limit). A subset of standard objects are monitored via the Streaming API as well.
  • dynamics

    • Only tracks add and update activity for supported object types. Please contact Kloudless Support if you’re interested in tracking delete activity.

Calendar Activity

Calendar activity data is available for the following services:

  • google_calendar

    • Administrator google_calendar accounts currently behave similarly to non-admin accounts and do not monitor org-wide calendar activity. They should therefore not be used to exclusively monitor the authenticating user’s calendar activity. This will be updated in the future.
  • outlook_calendar, exchange

    • Modifications to past activity are not currently tracked.

By default, Kloudless will monitor the user’s primary calendar and up to four additional calendars that the user owns. The calendars monitored can be updated in the account’s monitor_calendars attribute. See the account import and account update docs for more information.

Org-wide Activity

Org-wide activity tracking for all organization users is available for administrator accounts for the following services in Kloudless Enterprise:

  • box

  • dropbox

  • gdrive

    • Requires G Suite Enterprise.
  • egnyte

  • salesforce

  • sharepoint

  • onedrivebiz

Audit Activity

Audit activity can be retrieved through the normal activity endpoint, and will be available for administrator accounts for the following services:

  • azurerm

  • box

  • cloudtrail

  • dropbox

  • gdrive

    • Requires G Suite Enterprise.
  • onedrivebiz

  • sharepoint

  • slack

    • Requires Slack Enterprise Grid. Note that slack admin accounts prioritize providing org-wide activity, with granularity to the conversation level. To monitor message activity, either periodically list new messages in each channel, or use a separate non-admin account to monitor activity in channels that the account has access to.

You can find the list of Kloudless Audit activity here. This activity provides additional audit-type information for the account.

v2: Check out our v2 Audit Activity API for a comprehensive solution to track org-wide activity occurring in business applications. The initial release includes support for popular services such as Office 365, G Suite, Box, Dropbox, Egnyte, and Sharefile.

Activity latency

Activity data may not be provided right away. Latency prior to an update is configurable in self-hosted/private Kloudless Enterprise installations and varies in the cloud version as detailed below.

The following services notify Kloudless of changes to users’ accounts, with activity data updated in at most 1.5 minutes:

  • box

  • dropbox

  • evernote

  • gdrive

  • s3

    • New buckets are detected every 20 min.
  • smb

  • salesforce

  • google_calendar

  • outlook_calendar

  • sharefile

Other services require that we query the service repeatedly to find changes. This means that for the following services, activity data on average will be updated every 5 minutes on Kloudless’ cloud version, and every 1 minute in Kloudless Enterprise:

  • File-system traversal or equivalent

    • cq5
    • hubspot
    • jive
    • salesforce
    • webdav
  • Polling an API endpoint or equivalent

    • egnyte
    • sharefile
      • Polling is used for non-audit type activity collected for non-admin accounts.
    • sharepoint
      • Polling is used for non-audit type activity collected for non-admin accounts.
      • For Audit activity, latencies vary between Office 365 workloads. SharePoint, OneDrive for Business, and Azure Login activity are available within minutes. Others are documented here.
    • skydrive
    • onedrivebiz
      • See sharepoint.

The CMIS-like services listed below also poll for changes. To enable more efficient activity retrieval by Kloudless, please configure the repository to create a change log if possible.

  • alfresco

  • alfresco_cloud

  • cmis

  • documentum

  • filenet


Activity 

Overview

Actions such as creating, modifying, or deleting resources generate activity that we track. They are represented as a stream of Activity objects.

You need subscriptions to use Activity endpoints. To enable automatic subscriptions for your application, visit the Events Configuration page and ensure the checkbox for ‘Collect Events’ is checked. This creates default Subscription objects for any accounts connected or reconnected after this time automatically. With a default Subscription, you can use the default alias for the subscription_id when accessing the Subscription and Activity endpoints.

Alternately, you can create subscriptions by using Subscription endpoints. Please check Creating a Subscription.

Up to 10,000 activity objects over the previous 24 hours are stored temporarily in Kloudless’ database for efficient retrieval by each application.

Activity Attributes

Activity objects have the following attributes:

  • id: The id of the Activity object. May be None if activity are directly retrieved from the upstream service, or a string if the upstream activity ID is available. Will be a number representing the ID of the activity otherwise.

  • account: The id of the account the resource belongs to.

  • subscription: The id of the subscription the resource is monitored by.

  • modified: The time the activity occurred. This is not always precise due to the underlying service. Will be null if unavailable.

  • type: Any of the types described in Activity types.

  • ip: User’s IP Address, if available. May be null.

  • metadata: The new metadata of the resource or null if the action is delete and the data is unavailable.

  • previous_metadata: The metadata of the original resource prior to a rename, move, or copy. {} or absent if unavailable.

  • user_id: For admin accounts, this field specifies the ID of the user responsible for the activity.

Activity Types

Currently the following types of activity are available for objects belonging to the following APIs:

  • add: a resource has been created.

    • Resource’s API type: storage, crm, calendar, itsm, messaging.
  • delete: a resource has been deleted.

    • Resource’s API type: storage, crm, calendar, itsm, messaging.
  • update: a resource has been modified.

    • Resource’s API type: storage, crm, calendar, itsm, messaging.
  • rename: a resource has been renamed.

    • Resource’s API type: storage.
  • move: a resource has been moved.

    • Resource’s API type: storage.
  • copy: a resource has been copied.

    • Resource’s API type: storage.
  • restore: a resource has been restored after being deleted.

    • Resource’s API type: storage.

The CRM API activity applies to all standard Kloudless CRM objects. Activity data incidentally obtained for other CRM objects is also available during the process of activity retrieval as raw object data even if the data is not marshaled into the unified Kloudless API format.

The most specific activity is returned where possible; otherwise, the activity specified by the underlying service will be returned.

List Activity 

List activityGET /accounts/{account_id}/subscriptions/{subscription_id}/activity{?cursor,page_size,from,until}]

List activity monitored by this Subscription using this endpoint!

Activity occurring in an account is returned as a list of activity objects in the order that our system was made aware of them.

While there is a small chance that there will be duplicate activity in the activity stream, Kloudless takes steps to minimize duplicate activity where possible in order to properly reflect the current state of the monitored resources in the underlying upstream service. The net result of applying all activity should reflect the current state of the upstream service.

The response contains the following fields:

  • objects: List of the activity that has taken place. If no activity is available, then there are no objects left to paginate through using the cursor at this time.

  • cursor: A string identifying a location in the stream immediately after the activity described in objects.

  • count: Number of activity objects returned.

  • type: Will always be object_list.

  • api: Will always be activity.

The returned cursor should be used in subsequent requests so that only activity that has not been seen previously is returned.

Note: The remaining attribute has been deprecated due to limitations with performance and accuracy.

Use the default alias to access the default Subscription’s activity as shown in this example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/me/subscriptions/default/activity?cursor=121'

Time-Based Activity Retrieval

The parameters from and until retrieve activity within a specific time range directly from the upstream service. This is available for the following services:

  • box (admin only)

  • sharepoint (admin only)

  • onedrivebiz (admin only)

  • dropbox (admin only)

  • gdrive (admin only)

The cursor returned in the response is limited in range to the time range specified in the initial request. It cannot be used in conjunction with the parameters from and until in future requests as the range cannot be altered.

If an empty list of activity is returned, there is no activity within the time range specified, or after the cursor specified.

  • Parameters:

    • cursor (optional, string) … The last cursor in the activity stream that the application has seen. This can be retrieved from last_cursor returned in the subscription object if not known. The cursor can also be set to after-auth, which will retrieve activity that has occurred after the account was connected. This is useful if prior activity is unnecessary.

      This parameter cannot be used with from and until. Subsequent cursors returned by a request using those parameters will be restricted to the time range specified in the first request.

    • page_size = 1000 (optional, number) … Number of activity objects in the stream to return, if available. The page_size must be greater than or equal to 1 and less than or equal to 1000. Treated as advisory.

    • from (optional, string) … An ISO-8601 string specifying the time of the oldest activity in the range to return (inclusive). Can be used without until.

    • until (optional, string) … An ISO-8601 string specifying the latest time prior to which to return activity (exclusive). Must be used along with from. Non-overlapping queries can be performed since the activity times are in the range [from, until). Future cursor values returned are limited in range to the until value provided in the first request.

  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "cursor": 330,
      "count": 5,
      "objects": [
        {
          "metadata": {
            "size": 5422,
            "mime_type": "image/png",
            "downloadable": true,
            "id": "Ffh__5fKqvbBc58zRvTe4KN3zhTSzmKoyLcQPUjAwr7-UoZmRQcmoKFNe5OZtFsmA_eKpgOPrEy6IqqE3K8klbw==",
            "type": "file",
            "account": 613076,
            "name": "logo_white_146x58.png",
            "parent": {
              "id": "FhUnU-Ri3DF0hQ5cU9wC7sTzChcbRsiEGuJ2g1sh5OcIbuF6JacDq7Ac7HsHC-mfC4Lkw-4MaaFHtv1CqwYlHGw==",
              "name": "Shared Documents"
            },
            "ancestors": null,
            "owner": {
                "id": "n1nNjHU4FP37p2VEmtZqmLQFN4BydJwiPV5YdiSqO="
            },
            "created": null,
            "modified": "2015-10-02T21:38:03Z",
            "path": "/Shared Documents/logo_white_146x58.png"
          },
          "action": "+",
          "account": 613076,
          "id": 320,
          "user_id": null,
          "type": "add",
          "previous_metadata": {},
        },
        {
          "metadata": {
            "size": 5391,
            "mime_type": "image/png",
            "downloadable": true,
            "id": "FYs8EY4mXgR6qgWYcEmocoygVtj1DUm29ABlZ-5tsmOSmdithPoA_yzYHlmpd6aFqTzxjVZOld0Uxud_l99Y7hw==",
            "type": "file",
            "account": 613076,
            "name": "test (2).png",
            "parent": {
              "id": "FhUnU-Ri3DF0hQ5cU9wC7sTzChcbRsiEGuJ2g1sh5OcIbuF6JacDq7Ac7HsHC-mfC4Lkw-4MaaFHtv1CqwYlHGw==",
              "name": "Shared Documents"
            },
            "ancestors": null,
            "owner": {
                "id": "rVzgcMEDWTNGchDV7FqDqzVKdqZSkEuCJjeOj="
            },
            "created": null,
            "modified": "2015-10-02T20:52:41Z",
            "path": "/Shared Documents/test (2).png"
          },
          "action": "+",
          "account": 613076,
          "id": 326,
          "user_id": null,
          "type": "add",
          "previous_metadata": {},
        },
        {
          "metadata": {
            "size": 5391,
            "mime_type": "image/png",
            "downloadable": true,
            "id": "FYs8EY4mXgR6qgWYcEmocoygVtj1DUm29ABlZ-5tsmOSmdithPoA_yzYHlmpd6aFqTzxjVZOld0Uxud_l99Y7hw==",
            "type": "file",
            "account": 613076,
            "name": "test (2).png",
            "parent": {
              "id": "FhUnU-Ri3DF0hQ5cU9wC7sTzChcbRsiEGuJ2g1sh5OcIbuF6JacDq7Ac7HsHC-mfC4Lkw-4MaaFHtv1CqwYlHGw==",
              "name": "Shared Documents"
            },
            "ancestors": null,
            "owner": {
                "id": "rVzgcMEDWTNGchDV7FqDqzVKdqZSkEuCJjeOj="
            },
            "created": null,
            "modified": "2015-10-02T20:52:45Z",
            "path": "/Shared Documents/test (2).png"
          },
          "account": 613076,
          "id": 330,
          "user_id": null,
          "type": "delete",
          "previous_metadata": {},
        },
        {
          "id": 132944,
          "account": 145,
          "modified": "2016-08-16T00:54:29.279000Z",
          "type": "add",
          "user_id": null,
          "ip": null,
          "metadata": {
            "id": 482938193,
            "name": "Kloudless, Inc.",
            "owner": "company@salesforce.com",
            "industry_code": 541519,
            "industry": Information Technology,
            "employees": 25,
            "rating": Hot,
            "email": hello@kloudless.com,
            "website": "kloudless.com",
            "created": "2015-09-02T10:11:33.948274Z",
            "modified": "2015-09-03T15:43:12.847532Z",
            "description": "Cloud API Services. Storage, CRM, and more",
            "type": account
          },
        },
        {
          "id": 132945
          "account": 145,
          "modified": "2016-08-16T00:54:29.279000Z",
          "type": "update",
          "user_id": "uMsO3tKSabQ0s1=",
          "ip": null,
          "metadata": {
            "id": 1928381283,
            "account": 482938193,
            "owner": "company@salesforce.com",
            "campaign": 14855,
            "lead": "3586",
            "name": "Eliot Sun",
            "title": "CEO",
            "department": "Execs",
            "email": "hello@kloudless.com",
            "created": "2015-10-01T02:34:57.123832Z",
            "modified": "2015-10-05T03:13:87.857364Z",
            "description": "CEO and Co-founder of Kloudless, Inc.",
            "type": contact
          },
        },
      ],
      "type": "object_list",
      "api": "activity",
    }
    {
      "count": 1,
      "cursor": 1408133596,
      "objects": [
        {
          "id": "LTYyMDQzOTYxNTQ2NTk3MTc3Nzk=",
          "account": 338476387,
          "action": "+",
          "ip": "36.228.22.224",
          "modified": "2019-09-23T09:33:00.099000Z",
          "type": "add",
          "user_id": "uMTAwMzYzNTk2Mzg5MzExODAxOTMw",
          "metadata": {
            "id": "FVSShlCqQFxa07HhjqSE3jMrhGi9ENP0qVxNwdVL1Na9WjesFbWopDueL-mJdBHgN",
            "raw_id": "1ZJJBK4ZrEQR7mVyr5hRK3M5URg-GxPL6",
            "created": null,
            "modified": "2019-09-23T09:33:00.099000Z",
            "name": "Copy of DogeCool.jpg",
            "type": "file",
            "size": null,
            "path": null,
            "mime_type": "image/jpeg",
            "owner": {
              "api": "team",
              "id": "uYWRtaW5AZGV2ZWxvcGVycy5rbG91ZGxlc3MuY29t",
              "type": "user",
              "calendar_id": null,
              "href": "https://api.kloudless.com/v1/accounts/338476387/team/users/uYWRtaW5AZGV2ZWxvcGVycy5rbG91ZGxlc3MuY29t",
              "email": "admin@developers.kloudless.com",
              "id_type": "login"
            },
            "last_modifier": {
              "api": "team",
              "id": "uMTAwMzYzNTk2Mzg5MzExODAxOTMw",
              "type": "user",
              "calendar_id": null,
              "href": "https://api.kloudless.com/v1/accounts/338476387/team/users/uMTAwMzYzNTk2Mzg5MzExODAxOTMw",
              "email": "admin@developers.kloudless.com",
              "id_type": "default"
            },
            "ancestors": null,
            "account": 338476387
          }
        }
      ],
      "type": "object_list",
      "api": "events"
    }

Audit Activity 

v2: Check out our v2 Audit Activity API for a comprehensive solution to track org-wide activity occurring in business applications. The initial release includes support for popular services such as Office 365, G Suite, Box, Dropbox, Egnyte, and Sharefile.

The previous v1 docs are available for reference in our v2 migration guide.


Subscriptions 

A Kloudless Subscription object enables monitoring an upstream service’s activity and receiving webhook notifications for it. Activity monitoring begins once a Subscription is created for an account.

To enable automatic subscriptions for your application, visit the Events Configuration page and ensure the checkbox for ‘Collect Events’ is checked. This creates default Subscription objects for any accounts connected or reconnected after this time automatically. With a default Subscription, you can use the default alias for the subscription_id when accessing the Subscription and Activity endpoints.

Kloudless Subscriptions have the attributes below:

  • id Unique identifier for this Subscription. default can be used as an alias for the id of the Subscription that has default set to true.

  • account Account identifier this Subscription belongs to.

  • expiry ISO 8601 timestamp for when the Subscription expires. Kloudless will automatically refresh active Subscriptions that are close to expiring if possible.

  • last_cursor The most recent cursor for this Subscription. Can be used as the cursor when listing activity. This attribute will be left out when listing Subscriptions.

  • last_cursor_updated_at ISO 8601 timestamp of the most recent time last_cursor has been updated. This attribute will be left out when listing Subscriptions.

  • active Boolean indicating if the Subscription is active or not. Activity won’t be monitored for an inactive Subscription.

  • disable_reason Reason that the current Subscription is inactive.

  • default Boolean indicating if the Subscription is the default Subscription for this account. Setting a default Subscription helps access activity for this account without knowing the Subscription ID, by simply making a request to /subscriptions/default/activity instead. This is especially valuable when entire Kloudless applications are configured to automatically create subscriptions for all accounts connected to them. Defaults to false. Only one Subscription may be default for an account at any point in time.

  • created ISO 8601 timestamp indicating when the Subscription object was created.

  • modified ISO 8601 timestamp indicating when the Subscription object was last modified.

  • type Always subscription.

  • api Always activity.

Note: If an upstream account is inaccessible for 90 days, or subscriptions for it are unable to be renewed for that time period, the Kloudless Subscription state will be removed along with related Activity data.

List Subscriptions 

list subscriptionsGET /accounts/{account_id}/subscriptions

List Subscriptions for an account.

The response contains the following information:

  • total Total number of objects.

  • count Number of objects in objects list.

  • objects List of Subscription objects.

  • type Always object_list.

  • api Always activity.

Example requests:

curl -L -H 'Authorization: Bearer [TOKEN]' \
    https://api.kloudless.com/v1/accounts/me/subscriptions
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "total": 1,
      "count": 1,
      "objects": [
        {
          "id": 185,
          "account": 4,
          "type": "subscription",
          "api": "activity",
          "active": true,
          "disable_reason": "",
          "default": false,
          "expiry": "2019-05-02T08:31:43.587905Z",
          "created": "2019-04-25T08:18:34.053393Z",
          "modified": "2019-04-25T08:31:58.742193Z",
          "last_cursor_updated_at": "2019-04-25T08:31:58.394494Z",
          "last_cursor": 2334
        }
      ],
      "type": "object_list",
      "api": "activity"
    }

Create a Subscription 

create a subscriptionPOST /accounts/{account_id}/subscriptions

Create a Subscription for an account. Activity monitoring will begin once a Subscription has been created for a service. Currently, only one Subscription can be created per account.

Parameters:

  • active: Whether the Subscription is active.

  • internal_state: The internal state of the Subscription being imported. Omit this parameter if you’re not importing a Kloudless Subscription.

Example requests:

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPOST -d '{"active": true}' \
    'https://api.kloudless.com/v1/accounts/me/subscriptions/'
  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
    Content-Type: application/json

    Body

    {
      "active": true
    }
  • Response  201Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "id": 185,
      "account": 4,
      "type": "subscription",
      "api": "activity",
      "active": true,
      "disabled_reason": "",
      "default": false,
      "expiry": "2019-05-02T08:31:43.587905Z",
      "created": "2019-04-25T08:18:34.053393Z",
      "modified": "2019-04-25T08:31:58.742193Z",
      "last_cursor_updated_at": "2019-04-25T08:31:58.394494Z",
      "last_cursor": 2334
    }

Retrieve a Subscription 

retrieve a subscriptionGET /accounts/{account_id}/subscriptions/{subscription_id}

Retrieve information about a Subscription with a Subscription ID for the current account.

Example requests:

curl -L -H 'Authorization: Bearer [TOKEN]' \
    https://api.kloudless.com/v1/accounts/me/subscriptions/185
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "id": 185,
      "account": 4,
      "type": "subscription",
      "api": "activity",
      "active": true,
      "disabled_reason": "",
      "default": false,
      "expiry": "2019-05-02T08:31:43.587905Z",
      "created": "2019-04-25T08:18:34.053393Z",
      "modified": "2019-04-25T08:31:58.742193Z",
      "last_cursor_updated_at": "2019-04-25T08:31:58.394494Z",
      "last_cursor": 2334
    }

Update a Subscription 

update a subscriptionPATCH /accounts/{account_id}/subscriptions/{subscription_id}

Update a Subscription for an account.

Parameters:

  • active: Whether the Subscription is active.

  • internal_state: The internal state of the Subscription being imported. Omit this parameter if you’re not importing a Kloudless Subscription.

Example requests:

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPATCH -d '{"active": false}' \
    'https://api.kloudless.com/v1/accounts/me/subscriptions/185'
  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
    Content-Type: application/json

    Body

    {
      "active": false
    }
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "id": 185,
      "account": 4,
      "type": "subscription",
      "api": "activity",
      "active": false,
      "disable_reason": "deactivated_by_user",
      "default": false,
      "expiry": "2019-05-02T08:31:43.587905Z",
      "created": "2019-04-25T08:18:34.053393Z",
      "modified": "2019-04-25T08:31:58.742193Z",
      "last_cursor_updated_at": "2019-04-25T08:31:58.394494Z",
      "last_cursor": 2334
    }

Delete a Subscription 

delete a subscriptionDELETE /accounts/{account_id}/subscriptions/{subscription_id}

Delete a Subscription and all its related Activity.

Example request:

curl -L -H 'Authorization: Bearer [TOKEN]' \
    -XDELETE 'https://api.kloudless.com/v1/accounts/me/subscriptions/185'
  • Response  204

Webhooks 

Webhooks are a way to be notified when new activity is available for one of the accounts belonging to your application.

Webhooks can be created in the Event Configuration section of the developer portal. Here are two different types of webhook:

Each are described in further detail below.

JSON Webhooks

When a JSON Webhook is created, it will be tested by our servers to ensure that it works before saving it. In order for the test to “pass”, your application should respond with a 200 OK status and have just your application ID in the response body. The test webhook request is a POST with an empty JSON object ({}) in the request body.

Here is an example of JSON Webhook notification from Kloudless:

POST / HTTP/1.1
Host: yourapp.example.com
Accept-Encoding: identity
Content-Length: 37
X-Kloudless-Signature: DojsMH34VH3sD+lB8sNBRwkbc7FXyCIRvEbijoCOz9I=
Content-Type: application/json
User-Agent: kloudless-webhook/2.0

{"account": 123, "subscription": 321}

The most important part of the POST request above is the body, which is a JSON object. The JSON object contains two fields:

  • account The ID of the account that triggered the activity.

  • subscription The subscription ID which triggered the webhook.

list the activity available. The response contains a cursor your application must store .

When your application receives a webhook, use the account and subscription IDs to list activity, along with a cursor if your application has one available from a prior response. The response to the endpoint above contains a cursor your application must store in its database.

Each time your application receives a webhook, include the latest cursor from your database in the query parameters while listing activity using the endpoint described above, and store the new cursor returned. This process guarantees your application will only receive new activity, in the order Kloudless became aware of them, regardless of the number of webhooks or whether they were all received.

Verifying JSON Webhooks

Kloudless includes a signature of the request that you can use to ensure that the request came from Kloudless and is untempered with. Here is how the signature is defined:

Base64Encode(HMAC-SHA256([API Key], [request contents]))

[request contents] in the example above would be the string {"account": 123, "subscription": 321}. For applications with multiple API Keys, the API Key used in the signature will be the oldest active one available.

NOTE: Even though there is a signature, you should accept webhook requests over HTTPS if possible. This ensures that data is not leaked to or tampered with by third parties.

JSON Webhook Retries

If Kloudless doesn’t receive a HTTP response with a status code below 500 within 30 seconds (3.05 seconds for socket connection timeout and 27 seconds for read timeout), Kloudless assumes the webhook failed and attempts to retry it.

Kloudless retries webhooks with an exponential back-off. The initial time between retries is 1 second and the maximum time between retries can grow to 15 minutes. If the webhook continuously fails for 24 hours, Kloudless stops retrying until new activity is available after that time.

Amazon EventBridge Events

Kloudless is an Amazon EventBridge Partner. This means that you can receive Kloudless Activity within your AWS environment using EventBridge, and then route the activity and to AWS Lambda functions, Amazon EC2, SQS queues, or other valid EventBridge targets.

You can enable the Kloudless partner event source by searching for Kloudless within the Partner Event Sources list in your AWS EventBridge console.

Here is an example of an EventBridge event object:

{
    "detail-type": "eventbridge_webhook_notification",
    "source": "aws.partner/kloudless/your@email.com/api-id-123",
    "account": "111122223333",
    "time": "2017-12-22T18:43:48Z",
    "region": "us-west-1",
    "detail": {
        "account": 123,
        "subscription": 234,
        "activity": {
            "v1": [v1_activity_object],
            "v2": [v2_activity_object]
        }
    }
}

AWS wraps the Kloudless event payload within detail in an outer object that includes metadata about the EventBridge event. Here is a description of the fields Kloudless includes in the detail object:

  • account The ID of the account that triggered the activity.

  • subscription The subscription ID which triggered the webhook.

  • activity

    • v1 A version 1 activity object. Please check Activity for details.
    • v2 A version 2 activity object. Please check Audit Activity for details.

For more information on the top-level fields other than detail, please check AWS’ EventBridge Docs.

Filtering Events

AWS EventBridge Event Patterns can be used to filter EventBridge events.

For example, if you only want to receive version 2 activity where the event_category is storage, you can use the following EventBridge pattern to filter just that activity:

{
    "detail": {
        "activity": {
            "v2": {
                "event_category": ["storage"]
            }
        }
    }
}