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.
# 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
- Check the list of events available in CKEditor Cloud Services.
- Learn how to manage existing webhooks and create new ones.