Webhooks
Webhooks resemble a notification mechanism that can be used to build integrations with CKBox. CKBox sends an HTTP POST request to a configured URL when specified events are triggered.
Webhooks can be used for data synchronization between CKBox 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 to the assets.
# Benefits of using webhooks
By using webhooks while integrating your application with the CKBox you can make the integration more reliable. Webhooks enable real-time communication by instantly notifying external systems about specific events, such as file uploads, asset modifications or deletions. This allows integrated systems to remain synchronized, facilitating prompt responses to changes. It therefore enhances flexibility, efficiency and scalability.
# Examples
# Data synchronization
Webhooks can serve as a notification system for events like file uploads, modifications, or removals. This can improve synchronization with other systems. For example, an integrated system can follow these notifications to synchronize folder trees in external systems.
# Triggering other operations
Webhooks can initiate additional actions or processes in response to specific events detected by the webhook. For instance, upon receiving a notification of a file upload, a webhook can automatically trigger processes such as AI analysis, updating metadata, or notifying relevant stakeholders.
# Tracking user changes
Webhooks allow for the detection of actions like file uploads, modifications, or deletions performed by users. By leveraging webhooks, applications can promptly notify external systems of these changes, enabling efficient synchronization and facilitating comprehensive tracking of user activity within the application ecosystem.
# Security
Every webhook request sent from CKBox 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 CKBox 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 the operations you are performing are order-sensitive, you should add another layer of verification to your endpoint that handles the events.
# Webhook format
Each webhook request sent by CKBox 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 CKBox. It is triggered by a file uploaded to the environment with an ID of user-1.
{
environment_id: '6afdca1ba1e38969dea1',
event: 'asset.uploaded',
payload: {
workspace_id: '80e839331c4d8827c474',
asset: {
id: 'Ta1xyyjKGbvF',
name: 'image',
extension: 'jpeg',
url: {{fileUrl}},
images_urls: {{imageUrls}},
mime_type: 'image/jpeg',
category_id: '0055659e-464c-4ebf-bc4b-7b690fbdfb72',
size_in_bytes: 21104,
tags: [],
metadata: {
description: 'File description',
custom_attributes: {}
}
},
user: { id: 'user-1', role: 'User' }
},
sent_at: '2024-02-16T15:45:45.190Z'
}