Getting Started

Filestack Architecture

File Upload

File Export (Save To)

Responsive Images

Image Transformations

Document Transformations

Video Transcoding

Audio Transcoding





Filestack Viewer


Supported Cloud Drives

Filestack Recipes

Filestack Integrations

Filestack SDKs

Register for an API key

Filestack Webhooks

Filestack Webhooks serve the purpose of notifying users about events that occur in relation to their Filestack account. In your developer portal, you can set one or many urls whose purpose is to receive the messages triggered by specific Filestack events.

There are six event types that will send messages to your webhook url(s):

  • Dialog Opens
  • File Uploads
  • File Exports
  • File Conversions
  • File Overwrites
  • File Deletions
  • Video Conversions

Configuring Filestack Webhooks

Filestack Webhooks are configured in the developer portal under Credentials > Webhooks. On this page you will find a blank field with url example and a dropdown menu. You enter the webhook url where you will receive messages in the blank field, and then select what type of event message should be sent to that url. The final step is to click the add button. If you enter your url and select "All", then one entry will be made for each type of Filestack Webhook Event. If you have multiple applications in your account, you can set a different webhook URL for each API Key. After you have added your webhook urls, it can take up to 10 minutes for them to become active.

Receiving a Webhook Notification

Configuring your server to receive a new webhook is the same as creating any page on your website. If you are using Sinatra, add a new route with the desired URL. In PHP you could create a new .php file on your server. It doesn't need to be complicated. With webhooks, your server is the server receiving the request. You can even use an external service such as RequestBin as shown in the screenshot above.

When you receive a webhook, we request that your server return a 200 or 201 response.

Webhook data is sent as JSON in the request's body. The full event details are included and can be used directly. The "action" in the JSON is the type of Filestack event that happened, be it a file being uploaded, or simply the Filestack dialog opening.

We request that if you set up webhooks for testing, that you please remove the webhook urls from your portal when you are finished.

Note that for file uploads, both symlinks and files copied with pickAndStore, the "client" field shows the service used.

For conversions, the "provider" shows where the file resides. If the file was stored to Filestack's storage, the provider will be "internal", otherwise it could be "amazon" if the original was stored to S3, or if the link to the file was a symlink, the provider could be one of the cloud drives Filestack connects to, e.g. "Dropbox".

The following are examples of what the webhook messages include and look like:

  1. Dialog Open:

  2. {
      "action": "fp.dialog",
      "timestamp": 1435584646,
      "id": 102,
      "text": {
        "mimetypes": ["*/*"],
        "iframe": false,
        "language": "en",
        "id": "1435584650723",
        "mobile": false,
           "upsell": "false",
           "apikey": "YOUR_API_KEY",
              "saveas_subheader": "Save it down to your local device or onto the Cloud",
              "folder_subheader": "Choose a folder to share with this application",
              "open_subheader": "Choose from the files on your local device or the ones you have online",
              "folder_header": "Select a folder",
              "help_text": "",
              "saveas_header": "Save your file",
              "open_header": "Upload a file"
        "dialogType": "open",
        "auth": false,
        "welcome_header": "Upload a file",
        "welcome_subheader": "Choose from the files on your local device or the ones you have online",
        "help_text": "",
        "recent_path": "/",
        "extensions": null,
        "maxSize": 0,
        "signature": null,
        "policy": null,
        "custom_providers": "imgur,cloudapp",
        "intra": false

  3. File Upload (symlink):

  4. {  

  5. File Upload (with store):

  6. {
          "client":"Web Images",

  7. File Export (save to):

  8. {
      "action": "fp.export",
      "timestamp": 1444257665, 
      "id": 142447, 
        "source": "",
        "client": "Dropbox",
        "filename": "newFiletest.jpg",
        "created": ""

  9. File Conversion:

  10. {

  11. File Overwrite:

  12. {
      "action": "fp.overwrite",
      "timestamp": 1435588666,
      "id": 115,
        "url": "",
        "filename": "2.png"

  13. File Delete:

  14. {

  15. Video Conversion:

  16. {  
             "created_at":"2015/12/21 20:45:19 +0000",
             "started_encoding_at":"2015/12/21 20:45:22 +0000",
             "updated_at":"2015/12/21 20:45:32 +0000",
             "created_at":"2015/12/21 20:45:19 +0000",
             "updated_at":"2015/12/21 20:45:32 +0000",

For information about webhooks for specific cloud drives, please consult the following links: