Event-Based request format

Overview

This document describes the real-time webhook API endpoint that external integrators can use to notify the system about file events. The endpoint accepts different payload formats depending on the storage type.

Endpoint Information

URL: https://{baseurl}/api/webhook/realtime

Method: POST

Content-Type: application/json

For Box, the API endpoint is https://{baseurl}/api/webhook/realtime/public/{storageClientId}. Please refer to this article for specific instructions.

Request Format (with examples)

The request body differs based on storage type. Below are the specifications for each supported storage:

Amazon S3 and S3 Compatible

Format
Example (file in root)
Example (file in nested directory)
    
 
{    "storageClientId": \"{Storage Client Id}\",    "metadata": "{s3\": { \"object\": {\"key\": \"{Object Path}\" }}}"}
Copy

Alibaba Cloud

Format
Example (file in root)
Example (file in nested directory)
    
 
{    "metadata": "{\"oss\": {\"object\": {\"key\": \"{Object Path}\"}}}",    "storageClientId": \"{Storage Client ID}\"}
Copy

Google Cloud, Azure Blob, SMB Compatible, NFS and NetApp ONTAP

Format
Example (file in root)
Example (file in nested directory)
    
 
{    "metadata": "{\"Name\": \"{Object Path}\" }",    "storageClientId": \"{Storage Client ID}\"}
Copy

Response Formats

Success

When a webhook is successfully processed, the system returns:

Success response example
    
 
{    "correlationId": "67ea85a36f2f5732a82834d0"}
Copy

Field	Description
correlationId	A unique identifier that references the submitted file in our database. You can use this ID for tracking the file's processing status or for future API calls related to this file.

Error

When an error occurs during processing, the system returns:

Error response example
    
 
{    "responseKey": "REST_API_MSG_FAILED_STORAGE_RTP_NOT_ENABLED",    "responseMessage": "Real-Time Process is not enabled."}
Copy

Field	Description
responseKey	Machine-readable error code that identifies the specific error condition.
responseMessage	Human-readable explanation of the error.

Common error responses

Response Message	Description	Recommended Action
The storage could not be found	The specified storage client ID does not exist in the system.	Verify the storageClientId is correct and the storage has been properly configured in the system.
Real-Time Process is not enabled.	Real-time processing has not been activated for this storage client.	Enable real-time processing for the storage client in your account settings.
Real-Time Process is enabled, but it is not set to Event Based.	The storage is configured for real-time processing, but is using polling rather than event-based processing.	Stop the current RTP scan and start another one using Event-Based

Last updated on

Was this page helpful?