guideEvents

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 5 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 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:

  1. A collaboration session has ended.
  2. The document data has been successfully exported.
  3. The editorBundle is uploaded.
  4. 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.

# 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
        }
    },
    "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.

# 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
        }
    },
    "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.

# 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"
        }
    },
    "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 – The bundleVersion 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.

# 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>"
        }
    },
    "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.

# 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"
            }
        }
    },
    "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.

# 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"
            }
        }
    },
    "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 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 the editorBundle is uploaded for the environment. If some of the operations cannot be applied to the document, the data property is empty and the collaboration.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"
}