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.
# Collaboration
The following events can be triggered for the Collaboration service.
# User connected
Name: collaboration.user.connected
(previously document.user.connected
)
Description: Triggered when a user joins a collaboration session.
# Payload
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.
# Example
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"
}
# User disconnected
Name: collaboration.user.disconnected
(previously document.user.disconnected
)
Description: Triggered when a user disconnects from an active collaboration session.
# Payload
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.
# Example
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"
}
# Collaboration session updated
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.
# Payload
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.
# Example
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",
"version": 2000
}
},
"sent_at": "2019-05-29T08:17:56.761Z"
}
# Collaboration session update exported
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.
# Payload
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.
# Example
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"
}
# Collaboration session finished
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.
# Payload
document.id
– The ID of the removed document.document.removed_at
– The date of the document removal.
# Example
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"
}
# Collaboration session exported
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.
# Payload
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.
# Example
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"
}
# Collaboration session export failed
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.
# Payload
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.
# Example
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"
}
# Collaboration session recovered
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.
# Payload
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.
# Example
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"
}
# Document storage
Webhook requests from this section are sent only when the document storage feature is enabled and configured properly.
# Document saved
Name: storage.document.saved
Description: Triggered when the document data is saved.
# Payload
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.
# Example
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"
}
# Document save failed
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.
# Payload
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.
# Example
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"
}
# Document removed
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 CKEditor Ecosystem customer dashboard for SaaS or in the Management Panel for On-Premises, all stored documents are removed.
# Payload
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.
# Example
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"
}
# Comments
The following events can be triggered for the Comments service.
# Comment added
Name: comment.added
Description: Triggered when a comment is created.
# Payload
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.
# Example
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"
}
# Comment updated
Name: comment.updated
Description: Triggered when a comment is updated.
# Payload
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.
# Example
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"
}
# Comment removed
Name: comment.removed
Description: Triggered when a comment is removed.
# Payload
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.
# Example
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"
}
# Comment thread added
Name: commentthread.added
Description: Triggered when a comment thread is added.
# Payload
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.
# Example
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"
}
# Comment thread updated
Name: commentthread.updated
Description: Triggered when a comment thread is updated.
# Payload
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.context
– The updated context of the comment thread, required for the comments archive feature.comment_thread.attributes
– The updated attributes of the comment thread.
# Example
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",
"context": {
"type": "value"
},
"attributes": {
"attribute": "value"
}
}
},
"sent_at": "2019-05-29T08:17:53.457Z"
}
# Comment thread resolved
Name: commentthread.resolved
Description: Triggered whenever a comment thread is resolved.
# Payload
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.
# Example
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"
}
# Comment thread reopened
Name: commentthread.reopened
Description: Triggered whenever a comment thread is reopened.
# Payload
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.
# Example
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"
}
},
"sent_at": "2019-05-29T08:17:53.457Z"
}
# Comment thread removed
Name: commentthread.removed
Description: Triggered when a comment thread is removed.
# Payload
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.comments
– The list of comments from the removed comment thread.
# Example
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",
"comments": [
{
"id": "comment-1"
}
]
}
},
"sent_at": "2019-05-29T08:17:53.457Z"
}
# Comment thread restored
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.
# Payload
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.comments
– The list of comments from the restored comment thread.
# Example
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",
"comments": [
{
"id": "comment-1"
}
]
}
},
"sent_at": "2019-05-29T08:17:53.457Z"
}
# Comment threads removed
Name: commentthread.all.removed
Description: Triggered when all comment threads in a document are removed.
# Payload
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.
# Example
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"
}
# Suggestions
The following events can be triggered for the Track Changes service.
# Suggestion added
Name: suggestion.added
Description: Triggered whenever a suggestion is added.
# Payload
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.
# Example
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"
}
# Suggestion accepted
Name: suggestion.accepted
Description: Triggered whenever a suggestion is accepted.
# Payload
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.
# Example
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"
}
# Suggestion rejected
Name: suggestion.rejected
Description: Triggered whenever a suggestion is rejected.
# Payload
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.
# Example
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"
}
# Suggestion removed
Name: suggestion.removed
Description: Triggered whenever a suggestion is removed.
# Payload
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.
# Example
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"
}
},
"sent_at": "2019-05-29T08:17:56.761Z"
}
# Suggestion restored
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.
# Payload
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.
# Example
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"
}
},
"sent_at": "2019-05-29T08:17:56.761Z"
}
# Deprecated
The deprecated events are kept for backwards compatibility, however, it is not recommended to use them in new handlers.
# Collaboration session removed
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.
# Payload
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.
# Example
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"
}