Back to top

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.

  • 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]))

For applications with multiple API Keys, the API Key used in the signature will be the oldest 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.