Webhooks are web application URLs (such as https://www.example.org/my-hook) that you specify in your Settings profile for FileSpin service to provide automatic callback notification of events such as asset uploads, updates, etc.
You save multiple webhooks in your settings profile to receive these callback notifcations.
Asset Events
Webhook callbacks are issued for the following asset events:-
| Event | Description |
|---|---|
| file-saved | When a file is stored in your storage after user uploads a file through File Picker or through Upload API |
| file-processed | When image and video conversions are processed for a file as part of upload workflow or via Image or Video Conversion API |
| file-data-updated | When custom data is attached to a file using FileSpin.update method of File Picker or using Update File Data API |
| file-deleted | When image conversions, video transcodes or the original file is deleted using Delete API |
| file-undeleted | When the original file is undeleted using Undelete API |
| addon-processed | An addon has completed processing |
Webhook callback will be attempted upto 8 times if Webhook does not respond with a HTTP 20x code (200, 201 or 202). If callback fails, re-attempts will follow a back-off algorithm that spreads calls out over an 8 hour period.
Webhook data format
The events and their webhook callback data format is as listed below:-
| Event | Data format |
|---|---|
| file-saved | Asset Data Format |
| file-processed | Asset Data Format |
| file-data-updated | Asset Data Format |
| file-deleted | See below |
| file-undeleted | See below |
| addon-processed | Asset Data Format |
On-demand image (ODI) is available for assets after they are processed the first time. Availability of ODI for an asset is indicated with the ON_DEMAND_IMAGE key in addons_info of Asset Data JSON.
"addons_info": {
"ON_DEMAND_IMAGE": {
"available": true
}
}
Unlike the other events, file-deleted and file-undeleted events only provide details about the deletion/undeletion and not the complete file details.
The data format for file-deleted and file-undeleted are as shown in the code sample to the right.
JSON Parameters
| Left | Center | Right |
|---|---|---|
| id | string | file id |
| event | string | file-deleted or file-undeleted |
| keys | JSON | list of keys sent in original request for deletion |
| status | string | "OK" if call was successful, "MAYBE" if FileSpin.io is uncertain (check the statusMsg in this case), "ERROR" if call could not be fully completed. If "ERROR" is returned, "errors" will contain specific error details for each failed key |
| message | string | Additional details about status |
| errors | JSON | Contains the keys that failed and specific error message. See sample response. |
Successful "file-deleted" event - Example data
{
"event": "file-deleted",
"id": "d78aa1a301ef4a2fbd8fa0cffd835b79",
"keys": ["deepzoom"],
"status": "OK",
"statusMsg": ""
}
Unsuccessful "file-deleted" event - Example data
{
"event": "file-deleted",
"id": "d78aa1a301ef4a2fbd8fa0cffd835b79",
"keys": ["deepzoom"],
"status": "ERROR",
"message": "S3 Permission denied",
"errors": {
"deepzoom": "S3 Permission denied"
}
}
Successful "file-undeleted" event - Example data
{
"event": "file-undeleted",
"id": "d78aa1a301ef4a2fbd8fa0cffd835b79",
"keys": ["original"],
"status": "OK",
"message": ""
}
Unsuccessful "file-undeleted" event - Example data
{
"event": "file-undeleted",
"id": "d78aa1a301ef4a2fbd8fa0cffd835b79",
"keys": ["original"],
"status": "ERROR",
"message": "Undeletion error"
}