Events
Each event corresponds with a certain action that can happen in CKEditor Cloud Services in a certain environment. Also, each event has a specific payload format with the relevant event information.
Before you use Webhooks, please get familiar with the basic principals of the feature. You can read more about how to use Webhooks in the Overview article.
The following events can be triggered for the Collaboration service.
Name: collaboration.user.connected
(previously document.user.connected
)
Description: Triggered when a user joins a collaboration session.
document.id
– The ID of the document that the user connected to.user.id
– The ID of the user.connected_users
– The list of currently connected users.
The following example presents a webhook request sent after a user connected to the document.
{
"event": "collaboration.user.connected",
"environment_id": "environment-1",
"payload": {
"user": {
"id": "user-1"
},
"document": {
"id": "document-1"
},
"connected_users": [
{
"id": "user-2"
}
]
},
"sent_at": "2019-05-29T08:17:56.761Z"
}
Name: collaboration.user.disconnected
(previously document.user.disconnected
)
Description: Triggered when a user disconnects from an active collaboration session.
document.id
– The ID of the document that the user disconnected from.user.id
– The ID of the user.connected_users
– The list of currently connected users.
The following example presents a webhook request sent after a user disconnected from the document.
{
"event": "collaboration.user.disconnected",
"environment_id": "environment-1",
"payload": {
"user": {
"id": "user-1"
},
"document": {
"id": "document-1"
},
"connected_users": [
{
"id": "user-2"
}
]
},
"sent_at": "2019-05-29T08:17:56.761Z"
}
Name: collaboration.document.updated
Description: Triggered every 10 minutes or 5000 versions when the content of the collaboration session is being updated. The event will also be emitted when the last user disconnects from a collaboration session.
document.id
– The ID of the updated document.document.updated_at
– The date of the document update.document.updated_by
– The ID of the last user performing the update.document.version
– The version of the updated document.
The following example presents a webhook request sent after a document is updated.
{
"event": "collaboration.document.updated",
"environment_id": "environment-1",
"payload": {
"document": {
"id": "document-1",
"updated_at": "2019-05-29T08:17:56.761Z",
"updated_by": "user-1",
"version": 2000
}
},
"sent_at": "2019-05-29T08:17:56.761Z"
}
Name: collaboration.document.update.exported
Description: Triggered every 10 minutes or 5000 versions when the content of the collaboration session is being updated. The webhook is also triggered when the collaboration session ends and when the last user disconnects. It contains a document content session. All the following conditions have to be met:
- The
editorBundle
is uploaded. - The document storage feature is disabled.
document.id
– The ID of the updated document.document.updated_at
– The date of the document update.document.version
– The version of the updated document.document.status
– The status of an export.document.data
– The document content. The property can be empty if exporting a collaboration session failed.document.attributes
– The document attributes object. The property may be sent when a document has been exported from a multi-root editor.
The following example presents a webhook request sent after a document is updated.
{
"event": "collaboration.document.update.exported",
"environment_id": "environment-1",
"payload": {
"document": {
"id": "document-1",
"exported_at": "2019-05-29T08:17:56.761Z",
"version": 2000,
"status": "success",
"data": "<p>Document content</p>",
"attributes": { "foo": "bar" }
}
},
"sent_at": "2019-05-29T08:17:56.761Z"
}
Name: collaboration.document.finished
Description: Triggered when a collaboration session for a document has ended and the temporary data of the document has been removed. The webhook is triggered regardless of the document storage configuration. To receive the exported document data, use the collaboration.document.exported
webhook.
document.id
– The ID of the removed document.document.removed_at
– The date of the document removal.
The following example presents a webhook request sent after a collaboration session for a document has ended:
{
"event": "collaboration.document.finished",
"environment_id": "environment-1",
"payload": {
"document": {
"id": "document-1",
"removed_at": "2019-05-29T08:17:56.761Z"
}
},
"sent_at": "2019-05-29T08:17:56.761Z"
}
Name: collaboration.document.exported
Description: Triggered whenever all of the following conditions are met:
- A collaboration session has ended.
- The document data has been successfully exported.
- The
editorBundle
is uploaded. - The document storage is disabled.
document.id
– The ID of the removed document.document.data
– The data of the removed document.document.removed_at
– The date when the document has been removed.document.version
– The version of the removed document.document.attributes
– The document attributes object. The property may be sent when a document has been exported from a multi-root editor.
The following example presents a webhook request sent after a collaboration session has ended and the document data has been successfully exported:
{
"event": "collaboration.document.exported",
"environment_id": "environment-1",
"payload": {
"document": {
"id": "document-1",
"data": "<p>Document content</p>",
"removed_at": "2019-05-29T08:16:12.755Z",
"version": 10,
"attributes": { "foo": "bar" }
}
},
"sent_at": "2019-05-29T08:17:56.761Z"
}
Name: collaboration.document.export.failed
Description: Triggered whenever both of the following conditions are met: (1) the system cannot convert document operations after a collaboration session has ended, and (2) the document storage is disabled.
document.id
– The ID of the removed document.document.reason
– The reason of the failed document operations conversion.document.removed_at
– The date when the document has been removed.document.version
– The version of the removed document.
The following example presents a webhook request sent after a collaboration session for a document has ended, but some of its operations could not be applied:
{
"event": "collaboration.document.export.failed",
"environment_id": "environment-1",
"payload": {
"document": {
"id": "document-1",
"reason": "general-conversion-fail",
"removed_at": "2019-05-29T08:16:12.755Z",
"version": 10
}
},
"sent_at": "2019-05-29T08:17:56.761Z"
}
Name: collaboration.document.recovered
Description: Triggered when a collaboration session for a document has expired and the temporary data of the document have been removed but some of the document operations could not be applied. The webhook is sent only when the document storage feature is disabled, and it will contain only correctly applied operations.
document.id
– The ID of the removed document.document.removed_at
– The date of the document removal.document.data
– The data of the removed document including only the successfully applied operations.document.version
– The version of the removed document.document.attributes
– The document attributes object. The property may be sent when a document has been exported from a multi-root editor.
The following example presents a webhook request sent after a document has been removed but some of its operations could not be applied.
{
"event": "collaboration.document.recovered",
"environment_id": "environment-1",
"payload": {
"document": {
"id": "document-1",
"removed_at": "2019-05-29T08:17:56.761Z",
"data": "<p>Document content</p>",
"version": 10,
"attributes": { "foo": "bar" }
}
},
"sent_at": "2019-05-29T08:17:56.761Z"
}
Webhook requests from this section are sent only when the document storage feature is enabled and configured properly.
Name: storage.document.saved
Description: Triggered when the document data is saved.
document.id
– The ID of the saved document.document.saved_at
– The date of the document save.document.download_url
– The URL to download the document.document.attributes
– The document attributes object. The property may be sent when a document has been exported from a multi-root editor.
The following example presents a webhook request sent after a document is saved.
{
"event": "storage.document.saved",
"environment_id": "environment-1",
"payload": {
"document": {
"id": "document-1",
"saved_at": "2019-05-29T08:17:56.761Z",
"download_url": "/api/v5/environment-1/storage/document-1",
"attributes": { "foo": "bar" }
}
},
"sent_at": "2019-05-29T08:17:56.761Z"
}
Name: storage.document.save.failed
Description: Triggered when a document data save has failed. It may happen when a different editor bundle or its configuration is used on your website and the CKEditor Cloud Services server under the same bundleVersion
. Refer to the Editor bundle guide for more information.
document.id
– The ID of the document.document.failed_at
– The date of the document save failure.editor.bundleVersion
– ThebundleVersion
of the editor used during the save.fail.reason
– The reason of the document save failure.fail.details
– The details of the document save failure.fail.trace_id
– The trace ID of the document save failure.
The following example presents a webhook request sent after a document data save has failed.
{
"event": "storage.document.save.failed",
"environment_id": "environment-1",
"payload": {
"document": {
"id": "document-1",
"failed_at": "2019-05-29T08:17:56.761Z"
},
"editor": {
"bundleVersion": "some_unique_bundle_version"
},
"fail": {
"reason": "Error while processing document.",
"details": "model-position-fromjson-no-root: Cannot create position for document.",
"trace_id": "trace-id-1"
}
},
"sent_at": "2019-05-29T08:17:56.761Z"
}
Name: storage.document.removed
Description: Triggered when the document data is removed from the storage. The document can be removed using a REST API call (see the Storage REST API section) or when the document storage feature is being turned off. After you disable the feature in the Customer Portal for SaaS or in the Management Panel for On-Premises, all stored documents are removed.
document.id
– The ID of the document.document.removed_at
– The date of the document removal.document.data
– The data of the removed document.document.attributes
– The document attributes object. The property may be sent when a document has been exported from a multi-root editor.
The following example presents a webhook request sent after a document is removed from the storage.
{
"event": "storage.document.removed",
"environment_id": "environment-1",
"payload": {
"document": {
"id": "document-1",
"removed_at": "2019-05-29T08:17:56.761Z",
"data": "<p>Document content</p>",
"attributes": { "foo": "bar" }
}
},
"sent_at": "2019-05-29T08:17:56.761Z"
}
The following events can be triggered for the Comments service.
Name: comment.added
Description: Triggered when a comment is created.
document.id
– The ID of the document in which the comment was added.comment.id
– The ID of the added comment.comment.created_at
– The creation date of the comment.comment.content
– The content of the added comment.comment.attributes
– The attributes of the added comment.comment.thread_id
– The thread ID that the comment was added to.comment.user.id
– The ID of the author of the comment.comment.thread
– The optional field sent with data regarding comment archive feature.comment_thread.id
– The ID of the added comment thread.comment.thread.created_at
– The date of the comment thread creation.comment.thread.context
– The context of the comment thread, required for the comments archive feature.comment.thread.attributes
– The attributes of the added comment thread.
The following example presents a webhook request sent after a comment is added.
{
"event": "comment.added",
"environment_id": "environment-1",
"payload": {
"document": {
"id": "doc-1"
},
"comment": {
"id": "comment-1",
"created_at": "2019-05-29T08:17:53.450Z",
"content": "Some comment content.",
"attributes": { "foo": "bar" },
"thread_id": "thread-1",
"user": {
"id": "user-1"
},
"thread": {
"id": "thread-1",
"created_at": "2019-05-29T08:17:53.450Z",
"context": {
"type": "value"
},
"attributes": {
"attribute": "value"
}
}
}
},
"sent_at": "2019-05-29T08:17:53.457Z"
}
Name: comment.updated
Description: Triggered when a comment is updated.
document.id
– The ID of the document in which the comment was updated.comment.id
– The ID of the updated comment.comment.updated_at
– The date of the comment update.comment.content
– The content of the updated comment.comment.old_content
– The old content of the updated comment.comment.attributes
– The attributes of the updated comment.comment.old_attributes
– The old attributes of the updated comment.comment.thread_id
– The thread ID in which the comment was updated.comment.user.id
– The ID of the author of the updated comment.comment.thread
– The optional field sent with data regarding comment archive feature.comment_thread.id
– The ID of the added comment thread.comment.thread.created_at
– The date of the comment thread creation.comment.thread.context
– The context of the comment thread, required for the comments archive feature.comment.thread.resolved_at
– The date of the comment thread resolve. Sent only when a comment thread is resolved.comment.thread_resolved_by
– The id of the user who resolved the comment thread. Sent only when a comment thread is resolved.comment.thread.attributes
– The attributes of the added comment thread.
The following example presents a webhook request sent after a comment is updated.
{
"event": "comment.updated",
"environment_id": "environment-1",
"payload": {
"document": {
"id": "doc-1"
},
"comment": {
"id": "comment-1",
"updated_at": "2019-05-29T08:17:53.450Z",
"content": "Some comment content.",
"old_content": "Some old comment content.",
"attributes": {
"foo": "new"
},
"old_attributes": {
"foo": "old"
},
"thread_id": "thread-1",
"user": {
"id": "user-1"
},
"thread": {
"id": "thread-1",
"created_at": "2019-05-29T08:17:53.450Z",
"context": {
"type": "value"
},
"resolved_at": "2019-05-29T08:17:53.450Z",
"resolved_by": "user-1",
"attributes": {
"attribute": "value"
}
}
}
},
"sent_at": "2019-05-29T08:17:53.457Z"
}
Name: comment.removed
Description: Triggered when a comment is removed.
document.id
– The ID of the document from which the comment was removed.comment.id
– The ID of the removed comment.comment.removed_at
– The date of the comment removal.comment.user.id
– The ID of the user who removed the comment.
The following example presents a webhook request sent after a comment is removed.
{
"event": "comment.removed",
"environment_id": "environment-1",
"payload": {
"document": {
"id": "doc-1"
},
"comment": {
"id": "comment-1",
"removed_at": "2019-05-29T08:17:53.450Z",
"user": {
"id": "user-1"
}
}
},
"sent_at": "2019-05-29T08:17:53.457Z"
}
Name: commentthread.added
Description: Triggered when a comment thread is added.
document.id
– The ID of the document from which the comment thread was added.comment_thread.id
– The ID of the added comment thread.comment_thread.comments
– The list of comments from the added comment thread.comment_thread.created_at
– The date of the comment thread creation.comment_thread.context
– The context of the comment thread, required for the comments archive feature.comment_thread.attributes
– The attributes of the added comment thread.
The following example presents a webhook request sent after a comment thread is added.
{
"event": "commentthread.added",
"environment_id": "environment-1",
"payload": {
"document": {
"id": "doc-1"
},
"comment_thread": {
"id": "comment-thread-1",
"comments": [
{
"id": "comment-1",
"attributes": {
"foo": "bar"
},
"content": "Some comment content",
"user_id": "user-1",
"created_at": "2019-05-29T08:17:53.450Z"
}
],
"created_at": "2019-05-29T08:17:53.450Z",
"context": {
"type": "value"
},
"attributes": {
"attribute": "value"
}
}
},
"sent_at": "2019-05-29T08:17:53.457Z"
}
Name: commentthread.updated
Description: Triggered when a comment thread is updated.
document.id
– The ID of the document from which the comment thread was updated.comment_thread.id
– The ID of the updated comment thread.comment_thread.comments
– The list of comments IDs from the updated comment thread.comment_thread.updated_at
– The date of the comment thread update.comment_thread.updated_by
– The ID of the user who updated the comment thread.comment_thread.context
– The updated context of the comment thread, required for the comments archive feature.comment_thread.attributes
– The updated attributes of the comment thread.
The following example presents a webhook request sent after a comment thread is updated.
{
"event": "commentthread.updated",
"environment_id": "environment-1",
"payload": {
"document": {
"id": "doc-1"
},
"comment_thread": {
"id": "comment-thread-1",
"comments": [
{
"id": "comment-1"
}
],
"updated_at": "2019-05-29T08:17:53.450Z",
"updated_by": "user-1",
"context": {
"type": "value"
},
"attributes": {
"attribute": "value"
}
}
},
"sent_at": "2019-05-29T08:17:53.457Z"
}
Name: commentthread.resolved
Description: Triggered whenever a comment thread is resolved.
document.id
– The ID of the document from which the comment thread was resolved.comment_thread.id
– The ID of the resolved comment thread.comment_thread.comments
– The list of comment IDs from the resolved comment thread.comment_thread.resolved_at
– The date when the comment thread was resolved.comment_thread.resolved_by
– The id of the user who resolved the comment thread.
The following example presents a webhook request sent after a comment thread is resolved.
{
"event": "commentthread.resolved",
"environment_id": "environment-1",
"payload": {
"document": {
"id": "doc-1"
},
"comment_thread": {
"id": "comment-thread-1",
"comments": [
{
"id": "comment-1"
}
],
"resolved_at": "2019-05-29T08:17:53.450Z",
"resolved_by": "user-1"
}
},
"sent_at": "2019-05-29T08:17:53.457Z"
}
Name: commentthread.reopened
Description: Triggered whenever a comment thread is reopened.
document.id
– The ID of the document from which the comment thread was reopened.comment_thread.id
– The ID of the reopened comment thread.comment_thread.comments
– The list of comment IDs from the reopened comment thread.comment_thread.reopened_at
– The date whe the comment thread was reopened.comment_thread.reopened_by
– The ID of the user who reopened the comment thread.
The following example presents a webhook request sent after a comment thread is reopen.
{
"event": "commentthread.reopened",
"environment_id": "environment-1",
"payload": {
"document": {
"id": "doc-1"
},
"comment_thread": {
"id": "comment-thread-1",
"comments": [
{
"id": "comment-1"
}
],
"reopened_at": "2019-05-29T08:17:53.450Z",
"reopened_by": "user-1"
}
},
"sent_at": "2019-05-29T08:17:53.457Z"
}
Name: commentthread.removed
Description: Triggered when a comment thread is removed.
document.id
– The ID of the document from which the comment thread was removed.comment_thread.id
– The ID of the removed comment thread.comment_thread.removed_at
– The date of the comment thread removal.comment_thread.removed_by
– The ID of the user who removed the comment thread.comment_thread.comments
– The list of comments from the removed comment thread.
The following example presents a webhook request sent after a comment thread is removed.
{
"event": "commentthread.removed",
"environment_id": "environment-1",
"payload": {
"document": {
"id": "doc-1"
},
"comment_thread": {
"id": "comment-thread-1",
"removed_at": "2019-05-29T08:17:53.450Z",
"removed_by": "user-1",
"comments": [
{
"id": "comment-1"
}
]
}
},
"sent_at": "2019-05-29T08:17:53.457Z"
}
Name: commentthread.restored
Description: Triggered when a comment thread is restored. A comment thread can be removed by removing the text in a document. The undo operation can restore the removed text but also restore the comment thread.
document.id
– The ID of the document where the comment thread was restored.comment_thread.id
– The ID of the restored comment thread.comment_thread.restored_at
– The date of the comment thread restoration.comment_thread.restored_by
– The ID of the user who restored the comment thread.comment_thread.comments
– The list of comments from the restored comment thread.
The following example presents a webhook request sent after a comment thread is restored.
{
"event": "commentthread.restored",
"environment_id": "environment-1",
"payload": {
"document": {
"id": "doc-1"
},
"comment_thread": {
"id": "comment-thread-1",
"restored_at": "2019-05-29T08:17:53.450Z",
"restored_by": "user-1",
"comments": [
{
"id": "comment-1"
}
]
}
},
"sent_at": "2019-05-29T08:17:53.457Z"
}
Name: commentthread.all.removed
Description: Triggered when all comment threads in a document are removed.
document.id
– The ID of the document from which the comment threads were removed.comment_threads
– The list of removed comment threads.comment_threads[].id
– The ID of the removed comment thread.comment_thread[].removed_at
– The date of the comment thread removal.comment_thread[].comments
– The list of comments from the removed comment threads.
The following example presents a webhook request sent after all comment threads are removed from a document.
{
"event": "commentthread.all.removed",
"environment_id": "environment-1",
"payload": {
"document": {
"id": "doc-1"
},
"comment_threads": [
{
"id": "comment-thread-1",
"removed_at": "2019-05-29T08:17:53.450Z",
"comments": [
{
"id": "comment-1"
}
]
},
{
"id": "comment-thread-2",
"removed_at": "2019-05-29T08:17:53.450Z",
"comments": [
{
"id": "comment-2"
}
]
}
]
},
"sent_at": "2019-05-29T08:17:53.457Z"
}
The following events can be triggered for the Track Changes service.
Name: suggestion.added
Description: Triggered whenever a suggestion is added.
document.id
– The ID of the document in which the suggestion was added.suggestion.id
– The ID of the suggestion.suggestion.created_at
– The creation date of the suggestion.suggestion.child_of
– The ID of the parent suggestion or null.suggestion.user.id
– The ID of the author of the suggestion.
The following example presents a webhook request sent after a suggestion is added.
{
"event": "suggestion.added",
"environment_id": "environment-1",
"payload": {
"document": {
"id": "document-1"
},
"suggestion": {
"id": "suggestion-1",
"created_at": "2019-05-29T08:17:53.450Z",
"child_of": null,
"user": {
"id": "user-1"
}
}
},
"sent_at": "2019-05-29T08:17:56.761Z"
}
Name: suggestion.accepted
Description: Triggered whenever a suggestion is accepted.
document.id
– The ID of the document in which the suggestion was added.suggestion.id
– The ID of the suggestion.suggestion.created_at
– The creation date of the suggestion.suggestion.updated_at
– The date of the suggestion update/accept.suggestion.user.id
– The ID of the user who accepted the suggestion.
The following example presents a webhook request sent after a suggestion is accepted.
{
"event": "suggestion.accepted",
"environment_id": "environment-1",
"payload": {
"document": {
"id": "document-1"
},
"suggestion": {
"id": "suggestion-1",
"created_at": "2019-05-29T08:17:53.450Z",
"updated_at": "2019-05-29T08:17:53.450Z",
"user": {
"id": "user-1"
}
}
},
"sent_at": "2019-05-29T08:17:56.761Z"
}
Name: suggestion.rejected
Description: Triggered whenever a suggestion is rejected.
document.id
– The ID of the document in which the suggestion was added.suggestion.id
– The ID of the suggestion.suggestion.created_at
– The creation date of the suggestion.suggestion.updated_at
– The date of the suggestion update/reject.suggestion.user.id
– The ID of the user who reject the suggestion.
The following example presents a webhook request sent after a suggestion is rejected.
{
"event": "suggestion.rejected",
"environment_id": "environment-1",
"payload": {
"document": {
"id": "document-1"
},
"suggestion": {
"id": "suggestion-1",
"created_at": "2019-05-29T08:17:53.450Z",
"updated_at": "2019-05-29T08:17:53.450Z",
"user": {
"id": "user-1"
}
}
},
"sent_at": "2019-05-29T08:17:56.761Z"
}
Name: suggestion.removed
Description: Triggered whenever a suggestion is removed.
document.id
– The ID of the document from which the suggestion was removed.suggestion.id
– The ID of the suggestion.suggestion.deleted_at
– The deletion date of the suggestion.suggestion.user.id
– The ID of the user who removed the suggestion.
The following example presents a webhook request sent after a suggestion is removed.
{
"event": "suggestion.removed",
"environment_id": "environment-1",
"payload": {
"document": {
"id": "document-1"
},
"suggestion": {
"id": "suggestion-1",
"deleted_at": "2019-05-29T08:17:53.450Z",
"user": {
"id": "user-id"
}
}
},
"sent_at": "2019-05-29T08:17:56.761Z"
}
Name: suggestion.restored
Description: Triggered whenever a suggestion is restored. A suggestion can be removed by removing the text in a document. The undo operation can restore the removed text but also restore the suggestion.
document.id
– The ID of the document where the suggestion was restored.suggestion.id
– The ID of the suggestion.suggestion.restored_at
– The restoration date of the suggestion.suggestion.user.id
– The ID of the user who restored the suggestion.
The following example presents a webhook request sent after a suggestion is restored.
{
"event": "suggestion.restored",
"environment_id": "environment-1",
"payload": {
"document": {
"id": "document-1"
},
"suggestion": {
"id": "suggestion-1",
"restored_at": "2019-05-29T08:17:53.450Z",
"user": {
"id": "user-1"
}
}
},
"sent_at": "2019-05-29T08:17:56.761Z"
}
The deprecated events are kept for backwards compatibility, however, it is not recommended to use them in new handlers.
Replaced by: collaboration.document.finished
and collaboration.document.exported
Name: collaboration.document.removed
(previously document.removed
)
Description: Triggered when a collaboration session for a document expires and the temporary data of the document is removed.
document.id
– The ID of the removed document.document.removed_at
– The date of the document removal.document.data
– The data of the removed document. This is an optional parameter that is set when the document storage feature is disabled and theeditorBundle
is uploaded for the environment. If some of the operations cannot be applied to the document, thedata
property is empty and thecollaboration.document.recovered
webhook is emitted.
The following example presents a webhook request sent after a document is removed.
{
"event": "collaboration.document.removed",
"environment_id": "environment-1",
"payload": {
"document": {
"id": "document-1",
"removed_at": "2019-05-29T08:17:56.761Z",
"data": "<p>Document content</p>"
}
},
"sent_at": "2019-05-29T08:17:56.761Z"
}