S3 Custom Source Integration

Uploads from the S3 Custom Source API support the following types of files:

All file types are selectable. This includes audio, video, image, text, office, and compressed archive files.

Section Quick Jump:

API OAUTH Webhooks


Using the S3 Custom Source API

  1. User selects the S3 Custom Source from the services list
  2. user is connected and can select files from the S3 bucket in the Filestack dialog

S3 Custom Source api upload widget

Upload from S3 Custom Source

Uploading or "picking" a file from S3 Custom Source in the context of Filestack means choosing a file and creating a distributable link to that file where it exists in S3 Custom Source. This is the Filestack URL that all "Pick" functions return. If you are using the pickAndStore method, then the file from S3 Custom Source is copied to a new storage location.

Sample Upload Code
filepicker.pick( { mimetypes: ['*/*'], services:['CUSTOMSOURCE'], }, function(Blob){ console.log(JSON.stringify(Blob)); } );

Download to S3 Custom Source

Exporting a file to S3 Custom Source with Filestack is not currently possible.

Sample Image Conversion Code for S3 Custom Source

If you have a Filestack Blob object or Filestack URL, then you can use the Filestack REST or Javascript APIs to convert office documents and image files. In the sample code below we "pick" an image file from S3 Custom Source and use the Javascript API convert method to resize the image to 400w by 400h in pixels.

Sample Conversion Code
filepicker.pick( { services: ['CUSTOMSOURCE'], mimetype: 'image/*', }, function(pickedBlob){ console.log("Conversion in progress...") filepicker.convert( pickedBlob, { width: 400, height: 400, }, { location: 'S3' }, function(convertedBlob){ console.log("Converted file url: ", convertedBlob.url); console.log("File is stored under your S3: ", convertedBlob.key); filepicker.remove( pickedBlob, function(){ console.log("Removed"); } ); } ); } );

Setting up a Custom S3 Source

The custom source feature allows a user to add their S3 storage bucket as a source to pick from in the side panel.

  1. In the developer portal, click on S3 Source under Credentials.
    Go to the S3 Source section under credentials in the Filestack developer portal
  2. Check the checkbox to enable the S3 Source feature.
  3. Enter the S3 Source Name, this is the name that will appear in the Filestack dialog side panel.
  4. Enter the S3 Access Key ID and Secret Access Key from your S3 account.
  5. Enter the name of the default S3 bucket users will be able to access.
  6. (Optional) Enter a sub-folder of the default bucket to restrict users to.
  7. Now log into your AWS account and go to the S3 console. In the S3 console, under the default bucket's properties, set a new rule in the permissions section.
    • The Grantee should be "Everyone".
    • Check off "List" to allow users to pick from the bucket.
    • Check off "Upload/Delete" if users should be able to add or remove files.
  8. Change the settings of your S3 Bucket to match the information above
  9. Add 'CUSTOMSOURCE' to the services parameter in your picker options and test to make sure your S3 Source shows up in your Filestack.
    add CUSTOMSOURCE to your Filestack services picker option
  10. Success!!!

Just add 'CUSTOMSOURCE' to the services parameter of your picker options after going through the steps above.

There are some picker option parameters that are specific to the S3 custom source. They allow you to choose the S3 bucket and path to display to customers on the fly.

Custom Source Client container
String
{customSourceContainer: 'mybucket'}

Specify the name of the S3 bucket to be used for your S3 Custom Source Client. This will override the default bucket set in your developer portal.

Custom Source Client path
String
{customSourcePath: 'some_folder/another_folder'}

Set the folder/path in the S3 bucket to use as the root path in your S3 Custom Source Client. This will override the default path set in your developer portal.

S3 Custom Source Webhooks for Your Application

S3 Custom Source 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.

These are the three event types that will send messages to your webhook url(s) concerning S3 Custom Source:

  • S3 Custom Source File Uploads
  • S3 Custom Source File Exports
  • S3 Custom Source File Conversions

Configuring S3 Custom Source Webhooks

Filestack Webhooks are configured in the developer portal under Credentials > Webhooks. If you enter your url and select "All", then one entry will be made for each type of Filestack Webhook Event, including the ones for S3 Custom Source. To learn more about configuring and receiving webhooks please visit our main webhooks documentation page.

Receiving a S3 Custom Source 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.

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.

Filestack will retry sending a webhook 3 times if the first attempt fails. The second attempt to deliver a webhook happens 5 minutes after the first attempt, the third attempt happens after 1 hour, and the final attempt to deliver a webhook happens 12 hours after the first attempt.

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 one of the cloud drives Filestack connects to, such as "S3 Custom Source" if the link to the file was a symlink.

The following are examples of what the S3 Custom Source specific webhook messages include and look like:

  1. File Upload (symlink):

  2. {  
       "action":"fp.upload",
       "timestamp":1443444905,
       "id":100946,
       "text":{  
          "url":"https://www.filestackapi.com/api/file/WAunDTTqQfCNWwUUyf6n",
          "client":"S3 Custom Source",
          "type":"image/jpeg",
          "filename":"1579337399020824.jpg",
          "size":139154
       }
    }

  3. File Upload (with store):

  4. {
       "action":"fp.upload",
       "timestamp":1443515345,
       "id":105258,
       "text":{
          "container":"kg_bucket",
          "url":"https://www.filestackapi.com/api/file/0CpUz9H4QfaX7LwwsgUf",
          "filename":"Cat_crying_Lolcat.jpg",
          "client":"S3 Custom Source",
          "key":"EqACdfNRmylz2h1SSYwT_Cat_crying_Lolcat.jpg",
          "type":"image/jpeg",
          "size":205354
       }
    }

  5. File Export (save to):

  6. {
      "action": "fp.export",
      "timestamp": 1444257665, 
      "id": 142447, 
      "text":{
        "source": "https://www.filestackapi.com/api/file/qHi4LxRh28IeEBdJcFpw",
        "client": "S3 Custom Source",
        "filename": "newFiletest.jpg",
        "created": "https://www.filestackapi.com/api/file/s40jJOQDGVr2T86cgOAe"
      }
    }
            

  7. File Conversion:

  8. {
       "action":"fp.converse",
       "timestamp":1435586806,
       "text":{
          "url":"https://www.filestackapi.com/api/file/uydUKAcTSsWB3g5HOsB4/convert?w=102",
          "link":{
             "writeable":true,
             "mimetype":"image/jpeg",
             "handle":"uydUKAcTSsWB3g5HOsB4",
             "url":"filepicker_upload_persist/pHSrbCRqSqeR1wh8USfY_1.jpeg",
             "created_at":"2015-06-29T13:31:02.204Z",
             "provider":"S3 Custom Source",
             "app_id":7876,
             "filename":"1.jpeg",
             "mongo_id":null,
             "_metadata":null,
             "access_tokens":[
    
             ],
             "is_folder":false,
             "persist":false,
             "user_id":null,
             "id":31968,
             "size":"111175"
          }
       },
       "id":109
    }