ID: 10236

Print Friendly, PDF & Email

Subscribe for Events API

API Request

POST /review/api/events/assets/subscribe/:id
Create and register the callback.

DELETE /review/api/events/assets/subscribe/:id
Delete the existing callback with the given id.

GET /review/api/events/assets/subscribe/:id
Get the details of the existing callback as JSON response.

 

HEADERS:

Cookie Zoom Authenticated Cookie

 

PATH PARAM

id

Unique subscription id(name) for the callback. Must be a unique string such as a GUID which has not been registered with Zoom. It has to be a minimum of 8 chars and a maximum of 40 chars. Must be URL safe string and must not contain any special chars except hyphen. Only allowed chars are a-z, A-Z, 0-9, –

An existing ID is replaced with last callback registered if already present.

 

POST BODY: queryParameters

Key Description Required Default
callback

URL to call on some event. Given URL would be called upon some event as registered by this request if changes are detected.

Yes
header

Header Value to be set in the request callback. More than one header query params can be specified

E.g header=Content-Type: application/json

Optional.
method

Define HTTP method to be used for callback.

Optional GET
successCode Http code to be used as success code else request will be marked as failed and will be retried. Optional 200
retryCount Maximum number of time to re-try before marking the request as permanently failed. Note: next retry is performed after 1 minute and can be configured on Server. Optional 3
requestType If ‘auto’ is specified as request type, then it will be set based on the data type sent to callback else it can be overridden by headers field. Optional auto
queryParam Query params can be specified for the callback. Query params are appended to the callback URL. More than one query params can be specified. Optional
watchMetadata

Notify the callback when an asset is updated with given set of MetadataKey and Value.

Syntax 1: MetadataKey=Value
For e.g: City==SFO, whenever some asset is assigned with metadata City field with SFO, callback URL will be triggered. 

Syntax 2: MetadataKey==*
Notify the callback when any value is assigned to the given metadata key.

Syntax 3: MetadataKey!=Value
Notify the callback when an asset is updated with given MetadataKey but not this value.

Syntax 2: *==*
Notify the callback for any change in metadata.

More than one pair can be specified and logical OR operation is performed by default unless overridden via logicalOperand.

Optional
watchPath

Monitors the directory or file for changes.

Syntax 1: * /defproj/acme/
Monitors the directory for new files addition or deletion

Syntax 2: + /defproj/acme/
Monitors the directory only for new file addition

Syntax 3: /defproj/acme/
Monitor the directory for only deletion

Syntax 4: * /defproj/acme/sample.png
Monitor Monitors the file for any kind of changes.

Syntax 5: /defproj/acme/sample.png
Does no monitoring on the file or directory but limits the scope of metadata matching.

Note: watchPath field will limit the scope of metadata matching. It is recommended to use watchPath with watchMetadata to reduce the scope of matching.

More than one can be specified and logical OR operation is performed.

Required /(Root)
logicalOperand Controls the logical operation between metadata watch. By default logical OR is used, which means event will be triggered if any metadata matches as per the given watchMetadata property. Possible values are: AND, OR  Optional OR

 

API Response

HTTP 200 OK

Response Syntax:

{ 
  "id": "Id passed in the request path parameter",
  "success": true,      #1
  "error": "Error Message when success is false"    #2
}

#Notes

  1. success(boolean): True value signifies that operation is completed without any errors. If success is false, an associated error is returned in the error field of JSON response. 
  2. error(string): This field is populated if any error occurred during the ingest and success value is set to false.

 

HTTP 401

Authentication failed. Occurs when the given cookie is not valid.

Curl Command

Syntax

curl -X POST "http://preview-server:8873/review/api/events/assets/subscribe/<RegisterEvenName>" \
  -H "Cookie: <Zoom Authenticated Cookie" \
  --data-urlencode "callback=<Some url for callback>" \
  --data-urlencode "header=<Authorization header if needed" \
  --data-urlencode "method=<POST or GET>" \
  --data-urlencode "successCode=200" \
  --data-urlencode "watchMetadata=<Metadata match condition>"  \
  --data-urlencode "watchPath=<Path match condition>"  \
  --data-urlencode "logicalOperand=<AND, OR>"

Example

curl -X POST \
 http://preview-server:8873/review/api/events/assets/subscribe/OnCityChangeInProjectAcme \
-H 'Cookie: b3ca73fb-c9db-4c26-a672-d1555c128b32' \
--data-urlencode "callback=http://acme.org/url/callback" \
--data-urlencode "header=Authorization: Basic..." \
--data-urlencode "method=POST" \
--data-urlencode "successCode=200" \
--data-urlencode "watchMetadata=IPTC_City=*" \
--data-urlencode "watchPath=* /acme/mydata" \
--data-urlencode "logicalOperand=OR"

Above example watches for a change in metadata IPTC_City in path /acme/mydata and also watches for any change in files in /acme/mydata, for addition, modification or deletion.

Once a change is detected, the callback URL will be called with assets information which are changes in JSON format.

Output

Success:

{
  "id": "OnCityChangeInProjectAcme",
  "success": true
}

 

Error

{
  "success": false,
  "error: "Permission denied. You don't have permission to work on events."
}


Data Format Submitted to Callback

Be default submitted data is in JSON, to change the data format or fields please contact Zoom support.

Data is submitted only when POST is used. In the case of GET, only callback URL is called.

Below is the given example of JSON data submitted to the callback in case of change. JSON data includes the details of the assets which are changed since the last called callback. An Id of the event is included in JSON format, so that receiver can identify the response.

{
  "success": true,
  "data": {
    "entry": [
      {
        "assetId": 1,
        "rrn": 12,
        "path": "/acme/test/1.png",
        "owner": "xyz",
        "action": "none|added|modified|deleted"
      },
      {
        "assetId": 2,
        "rrn": 12,
        "path": "/acme/test/1.png",
        "owner": "xyz",
        "action": "none|added|modified|deleted"
      },
      {}
    ]
  },
  "id": "Id corresponding to which event is triggered."
}