Webhooks

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 can save multiple webhooks in your settings profile to receive these callback notifications.

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

Retry Behavior

Webhook callback will be attempted up to 8 times if the 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
    }
  }

file-deleted and file-undeleted Events

Unlike the other events, file-deleted and file-undeleted events only provide details about the deletion/undeletion and not the complete file details.

JSON Parameters

Key	Type	Description
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 is uncertain (check the statusMsg in this case), "ERROR" if call could not be fully completed. If "ERROR", errors will contain details.
message	string	Additional details about status
errors	JSON	Contains the keys that failed and specific error message. See sample responses below.

Successful "file-deleted" event

{
  "event": "file-deleted",
  "id": "d78aa1a301ef4a2fbd8fa0cffd835b79",
  "keys": ["deepzoom"],
  "status": "OK",
  "statusMsg": ""
}

Unsuccessful "file-deleted" event

{
  "event": "file-deleted",
  "id": "d78aa1a301ef4a2fbd8fa0cffd835b79",
  "keys": ["deepzoom"],
  "status": "ERROR",
  "message": "S3 Permission denied",
  "errors": {
    "deepzoom": "S3 Permission denied"
  }
}

Successful "file-undeleted" event

{
  "event": "file-undeleted",
  "id": "d78aa1a301ef4a2fbd8fa0cffd835b79",
  "keys": ["original"],
  "status": "OK",
  "message": ""
}

Unsuccessful "file-undeleted" event

{
  "event": "file-undeleted",
  "id": "d78aa1a301ef4a2fbd8fa0cffd835b79",
  "keys": ["original"],
  "status": "ERROR",
  "message": "Undeletion error"
}