CKEditor Ecosystem Documentation
Search
Home/Cloud Services/Developer resources

Webhooks

Webhooks resemble a notification mechanism that can be used to build integrations with CKEditor Cloud Services. CKEditor Cloud Services sends an HTTP POST request to a configured URL when specified events are triggered.

Webhooks can be used for data synchronization between CKEditor Cloud Services and another system or to build a notifications system. For example, thanks to webhooks, the system might notify the users via email about changes made in the document.

# Benefits of using webhooks

By using webhooks while integrating your application with the CKEditor Collaboration Server you can make the integration more reliable. Your application will send requests to the CKEditor Collaboration Server only when it is needed, without any periodical requests. It will limit the transfer between both servers and the complexity of implementation, as webhooks are based on REST API endpoints. Webhooks are called almost immediately after specific event occur.

# Examples

# Synchronization of comments

One way of using webhooks can be synchronizing comments with your server. The application can register for comments-related events and add, remove and update comments in a external database according to data included in webhook event’s payloads.

# Comments notification

Another case where webhooks can be useful is a situation where editors needs to be informed about new comments in a document. Application can register for the comments.added webhook event, and after handling it can send email by using any external service providers.

# Saving document

The example of saving document with usage of webhooks and REST API is described in a Initializing and saving documents guide.

# User access monitoring

There may be a need for receiving information who and when connected to the document. It may be easy done with user.connected and user.disconnected event. Information who, when and for how long accessed the document may be collected by your application.

# Security

Every webhook request sent from CKEditor Cloud Services to the configured webhook URL has a signature and a timestamp. Thanks to this, every request received by the server can be checked and confirmed that it comes from CKEditor Cloud Services and has not been modified.

More information about the verification process of signing requests can be found in the Request signature guide.

# Webhook order

Please keep in mind that webhook events are sent asynchronously. You should, therefore, not rely on the order of the received events.

If operations you are performing are order-sensitive, you should add another layer of verification to your endpoint that handles events.

# Webhook format

Each webhook request sent by CKEditor Cloud Services has the following properties:

  • event – The name of the event that triggered the webhook.
  • environment_id – The ID of the environment.
  • sent_at – The date when the specified webhook was sent.
  • payload – The payload of the webhook. It contains the data about a specific event.

# Example

Below you can find an example of a sample webhook request sent by CKEditor Cloud Services. It is triggered by a comment added to the comment thread thread-1 in the document with an ID of doc-1 by the user with an ID of user-1.

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

# Example

In case of a mechanism, where documents are received through the collaboration.document.exported webhook and stored in an external database, the document.removed_at field from the payload of the webhook should be compared with a date from a previous event. It will secure application in a case where the order of a received event is changed and the current document will be overridden with an older version from an event which was received after the latest version. If the document.removed_at is older than the date already stored in the database, then saving documents should be skipped.

It helps you to avoid inconsistency between states of documents in databases.

# Next steps