CKEditor Ecosystem Documentation
Search
Home/Cloud Services/Guides

guideWebhooks

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.

# 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