Compliance & Events
Webex is an end-to-end encrypted cloud collaboration platform. Organizations have exclusive control over the management of their encryption keys as well as the confidentiality of their data.
anchorOverview
anchorBecause 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
anchorPermissions & 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.
In a 1:1 room between users of different organizations, either organization’s compliance officers can monitor and manage data created by both 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
anchorCompliance 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:
spark-compliance:recordings_read
spark-compliance:recordings_write
spark-compliance:events_read
spark-compliance:memberships_read
spark-compliance:memberships_write
spark-compliance:messages_read
spark-compliance:messages_write
spark-compliance:rooms_read
spark-compliance:rooms_write
spark-compliance:team_memberships_read
spark-compliance:team_memberships_write
spark-compliance:teams_read
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
anchorPlease 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
anchorIntroduction
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 (therooms
resource). The only supported event isupdated
.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.
Resource | created | updated | deleted | ended | read |
---|---|---|---|---|---|
Attachment Actions | X | ||||
Messages | X | X | X | ||
Memberships | X | X | X | ||
Space Classifications (rooms) | X | ||||
File Downloads | X | ||||
File Previews a.k.a. File Transcodings | X | ||||
Room Tabs | X | X | X | ||
Meetings | X | ||||
Meeting transcripts | X | ||||
Meeting messages | X | X | X | ||
Call Records(CDR) | X | ||||
Business Texts(SMS) | X |
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.
spark-compliance:events_read
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 eventresource
—which resource the event includestype
—the type of action which took place, such as created or deletedactorId
—the ID of the person which committed the activity for this eventorgId
—the ID of the organization for the actorappId
—the ID of the integration or bot which committed the activity for this eventcreated
—when the event took placedata
—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.