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.

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

# Collaboration

The following events can be triggered for the Collaboration service.

# User connected

Name: document.user.connected
Description: Triggered when a user is connected to a document.

# 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": "document.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: document.user.disconnected
Description: Triggered when a user is disconnected from a document.

# 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": "document.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 removed

Name: document.removed
Description: Triggered when a collaboration session for a 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.

# Example

The following example presents a webhook request sent after a document is removed.

{
    "event": "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"
}

# 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/v4/environment-1/documents/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 Documents REST API section) or when the document storage feature is being turned off. After you disable the feature in the CKEditor Ecosystem customer dashboard, 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"
}

# Track Changes

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"
}