anchorOverview

Because we recognize that some data in Webex may involve access to sensitive information about users and accounts, Webex Control Hub supports multiple types of administrator roles with access to different subsets of information. Webex Control Hub provides a full-service management experience supporting trials, purchasing, account and user configuration, adoption reports, and customer support. For more information about Webex Control Hub, please see this data sheet.

Within Webex Control Hub, you can associate administrative users with a specific role to ensure that the data within Webex remains in compliance with the legal standards in effect for an organization. This role is known as the Compliance Officer. Compliance officers can use the Webex REST API to access information within Webex to aid in compliance activities for their organization.

Additionally, the Webex REST API includes an Events API endpoint, which authorized third-party software can use to access, monitor, and archive the data created and shared by Webex users within an organization.

This guide will provide more detail about the Compliance Officer role, the Events API endpoint, and the types of permissions that can be used for data monitoring and management within Webex. It will also describe the monitoring controls that can be put into place to ensure that all activities within Webex are in full compliance with accepted business practices and internal standards.

anchorWebex Data

Permissions & Ownership

Data created within Webex belongs to the organization that owns the room (space). The owner of a group room is generally the organization for the person who created the room. For 1:1 rooms between users in different organizations, the organization that each person belongs to owns their participant’s content. Rooms created by bots are owned by the organization of the first non-bot participant.

Data access permissions within Webex vary depending on a few factors: the room creator, room membership, and organization membership. When a room is created, the organization associated with the creator is considered the owning organization for the room. If users from other organizations are added to the room, those organizations are participating organizations in the room.

In general, the following types of users will be viewing, creating, and managing data within Webex:

• Room participants—can send and view messages within the room.
• Room moderator—users can be assigned as a moderator by a room owner and have exclusive control of the room including the room’s title and participant list.
• Compliance officers for the owning organization—can monitor and manage all data within group rooms created by a member of the organization; can manage all content in 1:1 rooms, including those with external participants.
• Compliance officers for the participating organization-can monitor and manage data created by their users in rooms owned by another organization; can manage all content in 1:1 rooms with external participants.

Security & Privacy

A key management server (KMS) is responsible for the creation and security of the encryption keys the Webex clients use to encrypt and decrypt data and communications. It is architecturally and operationally separated from the rest of the Webex Cloud and its data is not accessible by any other components. Whether the KMS is managed by Cisco or installed and managed on-premise, data within the Webex Cloud is encrypted from end-to-end and is not decrypted until it reaches the API endpoint.

For more information about data security and privacy in Webex, please see the Webex Security White Paper.

anchorCompliance

Compliance Officer

The role of a compliance officer is to ensure that a company is conducting its business in full compliance with all laws and regulations that pertain to its particular industry, as well as professional standards, accepted business practices, and internal standards.

The Webex REST API has compliance authorization scopes that support the compliance officer’s role. Using these spark-compliance scopes, compliance officers will have access to, and the ability to manage, all data created by their organization such as messages or content attachments. Compliance officers can monitor data and take action to mitigate compliance issues that could arise.

Authorization Scopes

The spark-compliance scopes and their descriptions are listed below:

For instructions on how to add these scopes to your app and for a full list of all available authorization scopes see the Integrations/OAuth Guide.

Using the Compliance Scopes

Normally, Webex REST API users only have access to information related to their account, such as messages in rooms where they are members. The spark-compliance scopes provide access to information across the organization. For instance, if granted the spark-compliance:messages_read scope, messages will be available for all rooms within the organization, not just those that the authenticated compliance officer is a member of.

Several scopes provide access to write data or take action within an organization. If an action should be taken against certain data within Webex for compliance reasons, the Webex REST API can be used with an authentication token authorized with one of the above scopes to carry out the action. For example, if a message needs to be deleted, the spark-compliance:messages_write scope will be required. To delete the message, use the DELETE /messages endpoint. Similarly, if a member of a room, either a person or a bot, needs to be added or removed, the spark-compliance:memberships_write scope will be required and the membership can be deleted with the DELETE /memberships endpoint.

When using the appropriate spark-compliance: scopes and API endpoints, the authenticated user does not need to be a member of the room to take action. For example, a compliance officer who is not a member of a particular room can create, update, or delete the room's memberships with the spark-compliance:memberships_write scope.

anchorMeetings

Please refer to the Meetings documentation for details.

Meeting Recordings

Compliance officers are able to retrieve user recordings for analysis and compliance. There is a separate API endpoint for admins and compliance officers /admin/recordings, while regular users use /recordings. As it relates to recording deletion, a recycle bin and associated recording status is available. A user typically moves a recording to the recycle bin via the GUI and then either restores the recording or purges the recording from the recycle bin. Once purged, the recording isn't accessible to regular users any longer, but it is still accessible to the Compliance Officer until it is removed through the retention process. Compliance officers who want to retrieve user-deleted recordings must query the /events API for deleted recording events, and use the returned recording ID to retrieve the recording from /recordings/{id}. Regular users will see a 404 error.

anchorEvents

Introduction

The Events API endpoint gives developers access to events happening within their Webex organization. Events can be integrated with Data Loss Prevention (DLP) and CASB software to check for policy violations and to take action to resolve any issues. The events available for monitoring include activities such as posting messages, sending content such as files, and group space membership changes. The Events API endpoint can be integrated with your existing archiving software to archive an unlimited amount of Webex data. For access to events older than 90 days, the organization will need the Pro Pack for Webex Control Hub.

Use the Events API endpoint to access activities after they have occurred. Perhaps you need to replay every message sent to a room to comply with a legal audit process, or you need to know which rooms someone joined and left. The Events API endpoint will give you access to this information quickly and securely. In addition Webex provides a tool to uncover actions of a specific user in form of the eDiscovery report, available through the Webex Control Hub.

Known Limitations: Membership events generated as a result of a POST to /team/memberships do not currently contain a "roomType" or "isHidden" parameter.

Most events apply to an API resource of the same name. For example when a user creates a message a message creation event will be available. Some events though are not quite as straightforward to correlate. These include

• Attachment Actions events, which are part of Buttons&Cards and corresponding message creations.
• Space Classifications, which are Room Classifications (the rooms resource). The only supported event is updated.
• File Downloads, that get triggered whenever a user downloads a file.
• File Transcodings events, which are created when a user sees a preview of a file in their Webex client (title page).
• Call Records(CDR) events, which are created when a Webex Calling user makes or receives calls.
• Business Texts(SMS) events, which are created when a Webex Calling users sends or receives SMS messages.

Authorization Scopes

One scope for Events is available. Note that in order to use a spark-compliance scope you will need to be a designated compliance officer for your organization in Webex Control Hub. For instructions on how to add these scopes to your app and for a full list of all available authorization scopes see the Integrations/OAuth Guide.

Using Events

With the Events API endpoint you can retrieve information about user activities in Webex such as message activity in spaces, content or files shared, or user membership changes in spaces.

The spark-compliance:events_read scope can be used by compliance officers to retrieve events for the entire organization.

Each event contains a data object which mimics the Webex REST API resource (such as a message or membership) at the time the event took place. If properties are added to existing API resources, new events will include them; past events will not be updated to include the new properties.

When requesting a list of events from the API, the result may be split into pages. See the Pagination guide to learn how to navigate through paged API responses.

Example: Retrieve Created Messages

To retrieve all messages that have been created, use the List Events endpoint. Use URL query parameters to limit the response to include only events related to the messages resource and only created items by using: resource=messages&type=created.

GET https://webexapis.com/v1/events?resource=messages&type=created

{
  "items": [ {
    "id": "Y2lzY29zcGFyazovL3VzL0VWRU5UL2JiY2ViMWFkLTQzZjEtM2I1OC05MTQ3LWYxNGJiMGM0ZDE1NAo",
    "resource": "messages",
    "type": "created",
    "actorId": "Y2lzY29zcGFyazovL3VzL1BFT1BMRS9mNWIzNjE4Ny1jOGRkLTQ3MjctOGIyZi1mOWM0NDdmMjkwNDY",
    "orgId": "OTZhYmMyYWEtM2RjYy0xMWU1LWExNTItZmUzNDgxOWNkYzlh",
    "appId": "null",
    "created": "2015-10-18T14:26:16+00:00",
    "data": {
      "id": "Y2lzY29zcGFyazovL3VzL01FU1NBR0UvOTJkYjNiZTAtNDNiZC0xMWU2LThhZTktZGQ1YjNkZmM1NjVk",
      "roomId": "Y2lzY29zcGFyazovL3VzL1JPT00vYmJjZWIxYWQtNDNmMS0zYjU4LTkxNDctZjE0YmIwYzRkMTU0",
      "roomType": "group",
      "text": "PROJECT UPDATE - A new project plan has been published on Box: http://box.com/s/lf5vj. The PM for this project is Mike C. and the Engineering Manager is Jane W.",
      "personId": "Y2lzY29zcGFyazovL3VzL1BFT1BMRS9mNWIzNjE4Ny1jOGRkLTQ3MjctOGIyZi1mOWM0NDdmMjkwNDY",
      "personEmail": "matt@example.com",
      "attachments": [
        {
          "contentType": "application/vnd.microsoft.card.adaptive",
          "content": {
            ... omitted ...
          }
        }
      ],
      "created": "2015-10-18T14:26:16+00:00"
    }
  } ]
}

In this example response, only one record is returned, but let’s take a look at it in detail.

{
  "items": [ {
    "id": "Y2lzY29zcGFyazovL3VzL0VWRU5UL2JiY2ViMWFkLTQzZjEtM2I1OC05MTQ3LWYxNGJiMGM0ZDE1NAo",
    "resource": "messages",
    "type": "created",
    "actorId": "Y2lzY29zcGFyazovL3VzL1BFT1BMRS9mNWIzNjE4Ny1jOGRkLTQ3MjctOGIyZi1mOWM0NDdmMjkwNDY",
    "orgId": "OTZhYmMyYWEtM2RjYy0xMWU1LWExNTItZmUzNDgxOWNkYzlh",
    "appId": "null",
    "created": "2015-10-18T14:26:16+00:00",
    "data": {
      ... omitted ...
    }
  } ]
}

The event object returned contains several fields which describe the event. This includes:

• id—a unique ID for the event
• resource—which resource the event includes
• type—the type of action which took place, such as created or deleted
• actorId—the ID of the person which committed the activity for this event
• orgId—the ID of the organization for the actor
• appId—the ID of the integration or bot which committed the activity for this event
• created—when the event took place
• data—the data for the event

{
  "items": [ {
    ... omitted ...
    "data": {
      "id": "Y2lzY29zcGFyazovL3VzL01FU1NBR0UvOTJkYjNiZTAtNDNiZC0xMWU2LThhZTktZGQ1YjNkZmM1NjVk",
      "roomId": "Y2lzY29zcGFyazovL3VzL1JPT00vYmJjZWIxYWQtNDNmMS0zYjU4LTkxNDctZjE0YmIwYzRkMTU0",
      "roomType": "group",
      "text": "PROJECT UPDATE - A new project plan has been published on Box: http://box.com/s/lf5vj. The PM for this project is Mike C. and the Engineering Manager is Jane W.",
      "personId": "Y2lzY29zcGFyazovL3VzL1BFT1BMRS9mNWIzNjE4Ny1jOGRkLTQ3MjctOGIyZi1mOWM0NDdmMjkwNDY",
      "personEmail": "matt@example.com",
      "attachments": [
        {
          "contentType": "application/vnd.microsoft.card.adaptive",
          "content": {
            ... omitted ...
          }
        }
      ],
      "created": "2015-10-18T14:26:16+00:00"
    }
  } ]
}

Inside of the event object, the data object contains an object which represents the Webex REST API resource at the time the event took place. For instance, in this event, a message object represents a message at the time of its creation.

Example: Retrieve Deleted Messages and Files

To retrieve all messages that have been deleted, use the List Events endpoint. Use URL query parameters to limit the response to include only events related to the messages resource and only deleted items by using: resource=messages&type=deleted.

Deleted messages have a reference back to the original message. Here is an example response for a single message that was deleted.

 {
      "id": "Y2lzY29zcGFyazovL3VzL0VWRU5UL2MyZjhlMjYwLTgyYmUtMTFlYi1iYzdhLWNmZmIwNDA0Y2Y1YQ",
      "resource": "messages",
      "type": "deleted",
      "actorId": "Y2lzY29zcGFyazovL3VzL1BFT1BMRS82ZDg4MDc3MS05MTA4LTRiMzktYmJlOS02OWJiNjA2ODBmZTG”,
      "created": "2021-03-11T23:08:59.142Z",
      "data": {
        "id": "Y2lzY29zcGFyazovL3VzL01FU1NBR0UvNDYyMDQ4NTAtODJiZS0xMWViLWJkYmUtM2IyYWMxNWZlNjg5",
        "roomId": "Y2lzY29zcGFyazovL3VzL1JPT00vMGQ5MTg1ZDAtODJiZS0xMWViLWEyNGYtZDMxMWQ2NmMwNjBj",
        "roomType": "group",
        "personId": "Y2lzY29zcGFyazovL3VzL1BFT1BMRS82ZDg4MDc3MS05MTA4LTRiMzktYmJlOS02OWJiNjA2ODBmZTG”,
        "personEmail": “example@gmail.com"
      }
 }

For a Compliance Officer, it is important to understand what has been deleted. The way to go about it, is to use the message ID and query the /messages resource with it. Both the text and in this case file attachment are returned.

GET https://webexapis.com/v1/messages/Y2lzY29zcGFyazovL3VzL01FU1NBR0UvNDYyMDQ4NTAtODJiZS0xMWViLWJkYmUtM2IyYWMxNWZlNjg5

The sample response looks like this

{
  "id": "Y2lzY29zcGFyazovL3VzL01FU1NBR0UvNDYyMDQ4NTAtODJiZS0xMWViLWJkYmUtM2IyYWMxNWZlNjg5",
  "roomId": "Y2lzY29zcGFyazovL3VzL1JPT00vMGQ5MTg1ZDAtODJiZS0xMWViLWEyNGYtZDMxMWQ2NmMwNjBj",
  "roomType": "group",
  "text": "check this",
  "files": [
    "https://integration.webexapis.com/v1/contents/Y2lzY29zcGFyazovL3VzL0NPTlRFTlQvNDYyMDQ4NTAtODJiZS0xMWViLWJkYmUtM2IyYWMxNWZlNjg5LzA"
  ],
  "personId": "Y2lzY29zcGFyazovL3VzL1BFT1BMRS82ZDg4MDc3MS05MTA4LTRiMzktYmJlOS02OWJiNjA2ODBmZTG”,
  "personEmail": “example@gmail.com",
  "html": "<p>check this</p>",
  "created": "2021-03-11T23:05:29.685Z"
}

The deleted message had a file attachment. Any file attachment is always encapsulated into a message, even if the user did not supply any text. For the Compliance Officer to check the file that was deleted, they have to query the /contents URL. Only the Compliance Officer will have access to the file and only for the duration of the default retention period. Regular users and after the retention period the query will return a http 404. If the Compliance Officer tries to delete the message again they will receive a 410 error status, which should be avoided.

For more information about how to use the Events API endpoint, please see the Events API Reference.