Back to top

Introduction to the Events 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 Events API endpoints listed below.

Kloudless monitors accounts using a variety of service-specific implementations to be aware of activity occurring within each account.

The services that provide events for each API category are provided below.

Storage Events

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

  • alfresco

  • alfresco_cloud

  • box

  • cmis

  • cq5

  • dropbox

  • dynamics

  • egnyte

  • evernote

  • gdrive

  • hubspot

  • jive

  • onedrivebiz

  • s3

  • salesforce

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

  • sharepoint

    • Only the primary site collection’s Document Library will be tracked in our cloud version. Kloudless Enterprise tracks data in all site collections.
  • skydrive

  • smb

  • webdav

CRM Events

CRM event data is available for the following services:

  • salesforce

    • All custom objects are monitored as well.
  • dynamics

Calendar Events

Calendar event data is available for the following services:

  • google_calendar (coming soon)

  • outlook_calendar (coming soon)

Org-wide Events

Org-wide events for all organization users is available for admin accounts for the following services in Kloudless Enterprise:

  • box

  • dropbox

  • gdrive

  • egnyte

  • salesforce

  • sharepoint

  • onedrivebiz

Audit Events

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

  • azurerm

  • box

  • cloudtrail

  • dropbox

  • gdrive

  • onedrivebiz

  • sharepoint

You can find the list of Kloudless Audit events here. These events provide additional audit-type information for the account.

Event latency

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

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

  • box

  • dropbox

  • evernote

  • gdrive

  • s3

    • New buckets are detected every 20 min.
  • smb

Other services require that we poll to traverse the underlying file tree in order to find changes. This means that for the following services, event data will be updated on average every 15 min in our cloud and 5 min in private installs:

  • cq5

  • egnyte

  • hubspot

  • jive

  • onedrivebiz

  • salesforce

  • sharefile

  • sharepoint

  • skydrive

  • webdav

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

  • alfresco

  • alfresco_cloud

  • cmis

  • documentum

  • filenet


Events 

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

To enable access to event data for accounts connected to your application, visit the App Details page and ensure the checkbox for ‘Collect Events’ is checked.

Up to 10,000 events over the previous 24 hours are stored temporarily in Kloudless’s database for efficient retrieval by your application.

We currently present the following types of events where available for objects belonging to the following APIs:

  • add: a resource has been created

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

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

    • Resource’s API type: storage, crm
  • 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 events apply to all standard Kloudless CRM objects. We also provide event data incidentally obtained for other CRM objects during the process of event retrieval as raw object data even if the data is not marshalled into the unified Kloudless API format.

We will return the most specific event where possible; otherwise, we will return the event specified by the underlying service.

Event objects have the following attributes:

  • id: The id of the event that is created

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

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

  • type: Any of the types described in Event 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 event.

List Events 

list eventsGET /accounts/{account_id}/events{?cursor,page_size}

Events are retrieved using this endpoint. They are returned as a list of event objects in the order that our system was made aware of them. There is a small chance that there will be duplicate events in the stream, but the net result of applying all of these events will reflect the current state of the underlying storage service. Kloudless takes steps to minimize duplicate events where possible.

The response contains the following fields:

  • objects: List of the events that have taken place.

  • cursor: A number identifying a location in the stream immediately after the events described in objects.

  • count: Number of events returned.

  • remaining: Number of events remaining in the stream.

The returned cursor should be used in subsequent requests so that only events that have not been seen previously are returned.

Example Request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/123/events?cursor=121'
  • Parameters
  • cursor
    string (optional) 

    The last cursor in the event stream that your application has seen. The cursor can also be set to after-auth, which will retrieve events that have occurred after the account was connected. This is useful if prior events are unnecessary.

    page_size
    number (optional) Default: 1000 

    Number of events 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.

  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
      "cursor": 330,
      "count": 5,
      "remaining": 0,
      "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
          }
        }
      ]
    }

Retrieve Latest Cursor 

Retrieve Latest CursorGET /accounts/{account_id}/events/latest

This returns the latest cursor that is available. This makes it easier to start fetching new events immediately, rather than making a potentially large initial request.

This returns an object with a single field:

  • cursor: The most recent cursor for this account

Example Request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/123/events/latest'
  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
      "cursor": 29
    }

Audit Events 

Several services provide data appropriate for auditing purposes, which Kloudless makes available via the Events endpoint for admin accounts connected to your Kloudless application and accounts connected with the audit scope. An admin account is an account authenticated with the admin modifier.

While most audit data is presented as received via the Kloudless Event’s raw attribute, Kloudless maps recognized events to known event types and formats. Here are the possible event types Kloudless provides:

  • unknown: This is the default event type for an event that is not mapped to a Kloudless Audit Event type specified in this list. The raw data for the event object will provide access to the original event received from the third-party service for further analysis.

  • login: A user successfully logged into the account

  • login_failed: A user failed to log into the account

  • logout: A user successfully logged out of the account

  • share_link: A link to a resource was shared

  • unshare_link: A shared link to a resource was removed

  • share_update: A shared link to a resource was modified

  • collaboration_add: A collaborator was added to a resource

  • collaboration_invite: A collaborator was invited to a resource

  • collaboration_accept: A collaborator has accepted the invite to a resource

  • collaboration_delete: A collaborator was removed from a resource

  • collaboration_update: The resource’s collaborators were updated

  • view: The resource was viewed

  • download: The resource was downloaded

  • user_invite: A user has been invited

  • user_add: A new user was created

  • user_delete: A user was deleted

  • user_update: A user was updated

  • group_add: A new group was created

  • group_delete: A group was deleted

  • group_update: A group was updated

  • group_add_user: A user was added to a group

  • group_delete_user: A user was removed from a group

Audit Event objects may also have the fields below in lieu of metadata and previous_metadata. They may either not be present or default to {} where unavailable or not applicable.

  • user: Information on the user associated with the event. e.g.: The user that was created, or the user a resource was shared with.

  • previous_user: The previous user data that was modified.

  • group: Information on the group associated with the event.

  • previous_group: The previous group data that was modified.

  • link: Metadata on a shared link. Includes the link’s URL.

  • login: Metadata on a login or attempted login.

  • collaboration: Metadata on a collaboration

See the Team endpoints for more information on user and group objects.


WebHooks 

WebHooks are a way to become notified when new events become available for one of the accounts belonging to your application. Webhooks can be created in the Application Details section of the developer portal. When the 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 request body.

Here is an example standard webhooks requests:

POST / HTTP/1.1
Host: yourapp.example.com
Accept-Encoding: identity
Content-Length: 14
X-Kloudless-Signature: DojsMH34VH3sD+lB8sNBRwkbc7FXyCIRvEbijoCOz9I=
Content-Type: application/x-www-form-urlencoded
User-Agent: kloudless-webhook/1.0

account=593652

The most important part of the POST request above is the body, which is a normal HTTP form. The body of the form contains a single field, account, the value of which is the ID of the account that triggered the event. There will only be one account in each webhook request.

We provide a signature of the request that you can use to ensure that the request came from us and is untampered 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=593652. 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.