Introduction to the Activity API v2 

Start with our v1 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 v2 Activity API currently supports only a subset of services. For more information on services supported by our generally available Activity API, check out the v1 Docs. Information regarding Activity latency and retention can also be found in the v1 Docs.

The services that provide activity are listed below.

Audit Activity

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

  • box

  • dropbox

  • gdrive

    • Requires G Suite Enterprise.
  • onedrivebiz

  • sharepoint

  • sharefile

  • egnyte

By default, Kloudless projects have access to create, update, and delete activity for individual user accounts.

Contact us for access to the full suite of audit activity described below across all users in an organization via Kloudless admin accounts.


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.

Activity Object Fields

Kloudless collects several types of activity data from each service and takes steps to unify the data formats seen into a single representation of activity in any connected account. To this end, Kloudless has classified data into multiple categories.

The following fields describe the type of activity received:

The following fields describe information from Kloudless on the activity:

  • id: Identifier of the Kloudless Activity.

  • account: Account identifier of the connected Kloudless Service.

  • timestamp: The time that the activity occurred at. Formatted in ISO 8601. null if unavailable.

  • type: The type of object. Always activity.

  • api: The API from which this object was retrieved from. Always activity.

  • stream: The origin of activity data. Used to disambiguate when multiple overlapping sets of activity data are included. null if activity data is from a single source or can be de-duplicated by Kloudless. Currently only present for sharepoint and onedrivebiz.

  • impersonate_for_target: The ID of the user to impersonate to access the target resource, where applicable.

  • raw: Contains an object attribute with raw data.

The following fields describe unified information on the specific data of the activity:

  • session: An object that describes the actor’s session.

    • type: login
  • actor: An object with information describing the origin of the activity.

    • type: user or application.
  • target: Data on the target resource of the activity.

    • type: file, folder, etc.
  • metadata: Additional data provided on the activity details.

    • type: property, collaboration, etc.

Format

{
    'id': ,
    'account': ,
    'api': 'activity',
    'type': 'activity',
    'event_category': '',
    'event_type': '',
    'event_subtype': '',
    'target': {
      ...,
      'api': '',
      'type': ''
    },
    'previous_target': {}
    'impersonate_for_target': null,
    'timestamp': '',
    'session': {
      'type': 'login',
      'ip': '',
      'user_agent': ,
      ...,
    },
    'actor': {
        ...,
        'type': '',
        'api': '',
    },
    'metadata': [{
        'api': '',
        'type': ''
    }],
    'raw': {
        'object': {
            ...,
        }
    }
}

The target, actor, and metadata objects refer to various types of Kloudless objects, depending on the activity received. In addition, these represnetaitons contain less information than the full Kloudless object, which may be returned in other Kloudless API endpoints. Please use the type field within the object to determine the type of object.

Activity Objects

The objects returned by the Activity API may contain less information than the full Kloudless objects, which may be returned in other Kloudless API endpoints. You can use the id, type, and api attributes to retrieve their full metadata from other Kloudess API endpoints.

User

Please refer to v1 User docs.

Group

Please refer to v1 Group docs.

Domain

  • id: A unique identifier of the Kloudless Domain Object.

  • name: The name of the domain.

  • type: Always domain.

  • api: Always team.

Collaboration

  • id: The unique identifier of this Collaboration object.

  • resource: The resource object that this Collaboration object refers to.

  • modified: An ISO 8601 timestamp indicating when the Collaboration object was last modified.

  • created: An ISO 8601 timestamp indicating when the Collaboration object was created.

  • creator: The user that originally created this Collaboration object. May not be present if unavailable.

  • links: A list of Service Link objects which can be used to link to the resource.

  • permissions A list of Permission objects representing levels of access granted to other user, group, or domain.

  • type Always collaboration.

Permission

Please refer to Permission.

Please refer to Link.

Property

  • id: The unique identifier of this Property object.

  • property_id: The underlying service property ID.

  • template_id: The underlying service template/schema ID.

  • key: User-defined string containing key value.

  • key_type: String indicating type of data key value contains.

  • values: Dictionary containing property values.

  • target: The target role for the property. Can be either a user, group, or a domain.

  • modified: An ISO 8601 timestamp indicating when the Property object was last modified.

  • created: An ISO 8601 timestamp indicating when the Property object was created.

  • description: String with description for the Property Object.

  • type: Always property.

  • api: Always storage.

File

Please refer to v1 File docs.

Folder

Please refer to v1 Folder docs.

Email Message

Please refer to v1 Email Message docs.

Login

  • ip: The IP address of the user.

  • user_agent: The user-agent of the user.

  • city: The city name from which the user logged in.

  • region: The region from which the user logged in.

  • country: The country from which the user logged in.

  • device: The device information of the user used to log in.

  • access_method: The access method used to log in.

  • session_id: The session ID of the login session.

  • host_name: The host name of the login session.

  • type : Always login.

  • api : Always events.

Activity Classification

Event Categories

category indicates the object or concept to which the activity primarily relates. The category for unknown activity will be unknown. Kloudless may add additional categories to describe activity as we continue to improve handling of unknown activity. Here are the currently available categories:

  • authentication: Activity that relates primarily to instances of a user logging into or out of an account.

  • calendar: Activity that relates primarily to Calendar API objects, such as calendars, calendar events, etc.

  • collaboration: Activity that relates primarily to sharing, access policies, and roles.

  • object: Activity that relates primarily to generic objects

  • storage: Activity that relates primarily to file-like or folder-like objects.

  • team: Activity that relates primarily to Team API objects, such as Users and Groups.

  • unknown: Activity that Kloudless has not yet unified.

Event Types

type refers to a general action describing the activity. The type value will be one of the following:

  • add: A resource was created.

  • access: A resource was accessed.

  • update: A resource was updated.

  • delete: A resource was deleted.

  • error: An error occurred with a resource.

  • unknown: An unknown activity occurred with a resource.

Event Subtypes

subtype provides any available specificity about the objects and information involved in the activity and/or the actions or occurrences that generated it. The subtypes for each event_category may be duplicated, but mean the same and are located below:

authentication

  • login: a user logged in to a cloud service.

  • logout: a user logged out of a cloud service.

calendar

  • rename: a resource was renamed.

  • add_guest: a guest was added to an event.

  • remove_guest: a guest was removed from an event.

  • event_update_time: an event’s time was updated.

collaboration

  • permission_update_expiration: An existing permission’s expiration was updated for a resource.

  • permission_access_scope: The default access scope for a resource was updated.

  • permission_visibility: The default visibility of a resource was updated.

  • permission_invite: A pending permission was added for a resource.

  • permission_accept: A pending permission was accepted for a resource.

  • permission_reject: A pending permission was rejected for a resource.

  • permission_request: Requested pending permission for a resource.

  • link_update_expiration: A shared link’s expiration was updated for a resource.

  • link_update_password: A shared link’s password was updated for a resource.

storage

  • copy: a resource was created via copy.

  • download: a resource was downloaded.

  • move: a resource was moved.

  • parent_update: a resource was added to a new location.

  • preview: a resource was viewed.

  • print: a resource was printed.

  • rename: a resource was renamed.

  • revert: a resource was reverted to a previous version.

  • tag_create: a tag was created for a resource.

  • untrash: a resource was created via undelete/untrash.

team

  • add_user: a user was added to a group.

  • approve_user: a user was approved to join a group.

  • invite_user: a user was invited to join a group.

  • remove_user: a user was removed from a group.

  • rename: a resource was renamed.

  • revoke_user: a user’s invitation to join a group was revoked.

  • team_approve: a user was approved to join an organization.

  • team_reject: a user was rejected from joining an organization.

  • team_invite: a user was invited to join an organization.

  • team_request: a user requested to join an organization.

  • user_accept: a user accepted the invite to join a group.

  • user_reject: a user rejected the invite to join a group.

  • user_bulk_create: users were added to an organization in bulk.

  • password_update: a user’s password was updated.

unknown

  • unknown: an unknown subtype. The raw data contains further information.

Activity Endpoints

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.

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/v2/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

    {
      "count": 1,
      "cursor": "ceyJhZG1pbiI6IHsicGFnZV90b2tlbiI6IG51bGwsICJ==",
      "objects": [
        {
          "id": "LTYyMDQzOTYxNTQ2NTk3MTc3Nzk=",
          "account": 123479645,
          "timestamp": "2019-09-23T09:33:00.099000Z",
          "type": "activity",
          "api": "activity",
          "event_category": "storage",
          "event_type": "add",
          "event_subtype": "unknown",
          "actor": {
            "id": "fake_actor_id",
            "ids": {
              "default": "fake_actor_id",
              "login": "fake_actor_id_login"
            },
            "id_type": "default",
            "type": "user",
            "api": "team",
            "email": "address@email.com",
            "name": null
          },
          "target": {
            "id": "FVSShlCqQFxa07HhjqSE3jMrhGi9ENP0qVxNwdVL1Na9WjesFbWopDueL-mJdBHgN",
            "created": null,
            "modified": null,
            "name": "Copy of DogeCool.jpg",
            "size": null,
            "path": null,
            "ancestors": null,
            "parent": {
              "id": "FAgxry6XbFjWeh6O3VCJDAcBUEEyc3m0CyWGbXx61OZs=",
              "name": "Root"
            },
            "owner": {
              "api": "team",
              "id": "fake_actor_id_login",
              "type": "user",
              "calendar_id": null,
              "email": "address@email.com",
              "id_type": "login"
            },
            "account": 123479645,
            "type": "file",
            "api": "storage",
            "mime_type": "image/jpeg",
            "downloadable": true
          },
          "previous_target": null,
          "metadata": null,
          "session": {
            "ip": "123.123.123.123",
            "type": "login",
            "user_agent": null
          },
          "stream": "Report",
          "impersonate_for_target": "fake_actor_id_login"
        }
      ],
      "type": "object_list",
      "api": "activity"
    }

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.

  • monitored_resources Optional. A list of resource IDs indicating which resources are monitored by this Subscription. This field cannot be updated once written. To change it, delete and re-create the entire Subscription.

    The following services currently support this feature:

    • gdrive (non-admin only)
      • Configure up to four Shared Drives to monitor.
    • google_calendar, outlook_calendar
      • Configure up to five calendars to monitor.

    Kloudless will set sane defaults for this field if required and not provided. Here are the current list of defaults for each service:

    • gdrive (non-admin)
      • ["root"]
    • google_calendar, outlook_calendar
      • ["primary"]

    Refer to each Unified API’s docs for more information on reserved identifiers such as root for Storage and primary for Calendar.

  • monitored_resource_api Read-only. This field corresponds to the API category associated with the objects identified by monitored_resources.

  • monitored_resource_object_type Read-only. The object type of objects in monitored_resources.

  • subscription_type Possible values:

    • resource-change (default): This monitors any new activity in the account.
    • crawl: This performs an initial one-time retrieval of all file and folder metadata in the account, including across all users for admin accounts. All metadata found is published as new activity. This is currently limited to files and folders accessible via the Storage API. See crawl_type for where the metadata found is published.
    • sync (planned): Not yet implemented. This is similar to crawl but will copy files, folders, and objects found to a location in a configured account automatically.
  • crawl_type Only external is supported at the moment. Contact Kloudless to enable other values for your Subscriptions. Here are possible values:

    • external (default): The metadata found during the crawling is published to all configured webhooks, EventBridge receivers, and Google Cloud Pub/Sub topics.
  • 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/v2/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",
          "monitored_resources": [
            "root"
          ],
          "monitored_resource_object_type": "folder",
          "monitored_resource_api": "storage",
          "last_cursor_updated_at": "2019-04-25T08:31:58.394494Z",
          "last_cursor": "A2B3q74"
        }
      ],
      "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.

  • monitored_resources: Optional. A list of resource IDs indicating which resources are monitored by this Subscription.

Example requests:

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

How to create a Subscription that monitors specific calendars

This example creates a Subscription that only monitors the primary calendar and a calendar with the ID fdGVzdEBrbG91ZGxlc3MuY29t.

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

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

    Body

    {
      "active": true,
      "monitored_resources": [
        "primary",
        "fdGVzdEBrbG91ZGxlc3MuY29t"
      ]
    }
  • 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,
      "monitored_resources": [
        "root"
      ],
      "monitored_resource_object_type": "folder",
      "monitored_resource_api": "storage"
    }

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/v2/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,
      "monitored_resources": [
        "root"
      ],
      "monitored_resource_object_type": "folder",
      "monitored_resource_api": "storage"
    }

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/v2/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,
      "monitored_resources": [
        "root"
      ],
      "monitored_resource_object_type": "folder",
      "monitored_resource_api": "storage"
    }

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/v2/accounts/me/subscriptions/185'
  • Response  204

WebHooks 

Kloudless Webhooks are a way to be notified when new activity is available for one of the Accounts belonging to your Application.

Webhooks and similar notification mechanisms can be managed in the Events configuration section of the developer portal. Kloudless supports three types of notification mechanisms:

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 status code that includes just your Kloudless 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 a 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.

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 HTTP 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 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 The activity data in a legacy format.
    • v2 The activity data in Kloudless’ format for our v2 API and above. Please see the Activity section 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 activity where the Kloudless v2 event_category attribute is storage, you can use the following EventBridge pattern to filter for just that activity:

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

Google Cloud Pub/Sub Messages 

You can configure Kloudless to publish Activity to a Google Cloud Pub/Sub topic as messages, and then consume those messages via a Google Cloud Pub/Sub subscription. Please refer to the Google Cloud Pub/Sub section on the Events configuration page of the Developer Portal for more information on how to set up Google Cloud Pub/Sub notifications.

Here is an example of a Pub/Sub message Kloudless could send:

{
    "account": 123,
    "subscription": 234,
    "activity": {
        "v1": [v1_activity_object],
        "v2": [v2_activity_object]
    }
}

The message data contains the following fields:

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

  • subscription The subscription ID which triggered the webhook.

  • activity

    • v1 The activity data in a legacy format.
    • v2 The activity data in Kloudless’ format for our v2 API and above. Please see the Activity section for details.