Webhooks are automated messages generated by the Files.com platform to notify an external service of changes to your files. Use webhooks if you need an external system to react in realtime to changes in your file system.

Our Webhooks send an HTTP GET or POST request to the URL you specify whenever a file is uploaded, downloaded, modified, renamed, copied, or deleted. Information about the operation is included in the request, either as query string or body parameters. Webhooks are easy to use and can be integrated by anyone with server-side programming knowledge. Our webhooks have also been designed to integrate well with 3rd party webhook handlers, such as Zapier.

Uses

Webhooks are helpful for notifying external systems when folder contents change in your Files.com account. In addition to sending a message that particular file event happened, you can also configure a Files.com webhook to send the contents of the file to the webhook listener. Some example use cases are listed below, but you may find other ways to use Webhooks.

When new orders files are uploaded into your directory, notify the fulfillment system, which could the download the orders files and move them into an archive folder.

When video files are added to a directory, notify a pre-processor system that downloads the files in order to resize them, then deletes the originals from your account.

When files are downloaded from a folder for a specific customer, notify your CRM, which can record the activity within its own local database.

When timecard files are copied into your folder, automatically include the contents of those files in the webhook request that is sent to a scheduling system.

Webhook Settings

To create a Webhook for a folder you must be logged in as a site administrator or must have folder admin privileges on the folder.

Each webhook must have a Primary URL setting along with the Limit to a specific folder setting. The Primary URL is the address that will receive the webhook message. This must resolve to a public IP address rather than internal IP addresses like 192.168.x.x, 10.x.x.x, etc. If you are specifying a port for your address, you must use 80, 443, 8080, or 8443 only. If port 443 is used, the server hosting the address must have a valid SSL certificate configured.

You can add one or more Backup URLs for your webhook. Backup URLs have the same restrictions on IP address, port and SSL as the primary URL. When your webhook is triggered, the messages are sent to every URL you have configured, not just the primary URL.

The Limit to a specific folder setting will cause the webhook to only be triggered by actions in the specified folder and its subfolders. To apply the webhook to your entire site, either omit the Limit to a specific folder option or select your site's root folder with /

A webhook that applies to your entire site can only trigger on file activity that occurs within the Files.com system. File changes that occur directly on an attached Remote Server, even in a folder that is a Remote Server Mount, won't trigger webhooks.

Optional Settings for Webhooks

Optional webhook settings allow you to control when your messages are generated as well as customize the contents of the messages.

Customizing Webhook Triggers

The Which file actions trigger this notification? setting determines what types of activity send messages to your listener(s). If you do not supply triggers for your webhook, then all file activity in the folder will send messages to your listeners. You can specify any combination of the allowed trigger types.

Triggering by File Name Pattern Match

You can configure the webhook to trigger when specified file name patterns are matched using the What files trigger this webhook? setting. The first option, All files, is the default setting, and will generate message when there is activity for any file.

You can instead use the Only files matching specific patterns fields to add rules that limit when webhook messages will be sent. Multiple patterns can be specified. The file name pattern matching uses the globbing syntax. For example, to match a CSV (Comma Separated Value) file, use *.csv as a pattern.

Customizing the HTTP Method

The Method setting controls how the webhook request is sent to your listener urls - either GET or POST. GET is the default value. Including file contents with your request will always send a POST request. If your file names contain sensitive information or PII, you should configure your Webhooks to use the POST method so that the filenames are not automatically logged by your listener's web host.

Dedicated IPs

The options for specifying Dedicated IPs only apply when a Custom Domain has been configured for your site. If your site has dedicated IP addresses, you may choose whether the Files.com platform will use those dedicated IP addresses to send webhook requests. You can enable this to simplify networking rules for the webhook listener(s). If you do not have dedicated IP addresses, or you disable this option, then requests to your listener URLs originate from one of Files.com's default pool of IP Addresses.

Custom Headers

You can define your own Headers to be sent with the webhook request. The user-agent header will be set to "Files.com Webhook" by default; you can override user-agent header with this setting. When the request is sent via POST and the encoding of the message has been set to JSON or XML, the content-type header will be either application/json or application/XML to match the encoding.

Customizing Webhook Body Encoding

If you customize the HTTP method of a webhook to use the POST method, you can also add custom elements to be included in the body of webhook requests, as well as change the encoding of the webhook body. The table below lists the different encodings available for webhooks that use the POST method.

The body encoding setting is ignored if you are sending the contents of the file in the request because attaching the file contents defines how the request must be encoded.

Including File Data in Webhook Requests

To simplify business flows that need to immediately process the contents of files, such as ingesting each uploaded file into an ETL pipeline, you might choose to send the contents of files in the webhook request. The Attach the contents of the triggering file setting offers three options - don't include the file in the request, include the file contents as the request's body, or include the file contents as a form field.

The Attach the contents of the triggering file value is set to No file contents by default, which does not attach the triggering file's contents to the request.

If you select the Send file contents as request body option for the setting, the webhook request will contain only the contents of the file. None of the information about the triggering action is included along with the request, and the HTTP content-type header will be set to match the file's type. This type of request is always sent as a POST request.

When you select Send file contents in a field for the setting, you also must specify the name of the field to be used. The generated requests will be multipart/form-data requests, and the information about the triggering action is included in form fields.

If your webhook is configured to Send file contents as request body or Send file contents in a field, a file that exceeds 25MB will not trigger the webhook.

Files can only be attached for create, read, update, move, or copy file actions. If a file delete action triggers a webhook that sends file contents, the deleted file is not attached to the Webhook request.

Verifying Webhook Authenticity

If your webhook encoding is RAW, XML or JSON, you can include a special header with every request that can be used to verify the sender. In the Advanced Settings section of a Webhook, look for the Verification token field. This will be populated with a unique random string for the Webhook, and you can remove the token or choose to regenerate it.

When the Verification Token is not blank, the generated requests will include the x-files-signature header. To check the message's authenticity, create a string that is the verification token followed by the path of the triggering file for the message (do not insert a leading slash for the path) and then generate an MD5 hash of the result. The MD5 hash should exactly match the contents of the x-files-signature header.

If the Verification Token field is left blank, the Webhook's requests will not include an x-files-signature header.

In addition to the x-files-signature header you can verify that Webhook calls are coming from Files.com by only accepting requests from IP addresses in our list of published IP Addresses. All Files.com requests will originate from one of these addresses. You can simplify this list if you are using Dedicated IPs and have configured your Webhook to send from your assigned addresses.

For information on verifying webhooks using EV1 or EV2 encoding, see the Legacy Format Webhooks page.

Structure of the Webhook Request

Whenever any file or folder action occurs within a folder with a webhook, an HTTP GET or POST request will be sent to your corresponding webhook URL within a few minutes of the operation. Make sure to reply with an HTTP response code that indicates success (codes from 200 to 299).

File Action Details

Webhook requests will contain information about the file action that triggered the message. How this information is sent depends on the HTTP method, body encoding or file attachment settings for your webhook.

Expected Response Code

We expect an HTTP response status that indicates success (codes 200 through 299), so if we don't receive one we will try the webhooks again a few times over the next 3 days. We will notify you by email if a failure persists beyond that period. Your listener should return a HTTP response status as quickly as possible when the request is received. If there is any time-consuming processing to do, the listener should reply with a success code immediately and then pass the request information on to the system which will do the actual processing.

Interactions with Remote Servers

Because Files.com allows you to connect storage on other systems, file activity may happen through other services, such as directly uploading files to S3 through another interface.

How Remote Syncs Interact with Webhooks

Syncs that push files from a webhook path to a remote server will not trigger that webhook.

Syncs which pull files from remote servers into the webhook path will trigger webhook messages.

Remote Mount Activity Does Not Trigger Webhooks

Files.com does not monitor folders on Remote Server Mounts for activity. For realtime monitoring of uploads to a remote mounted folder, use a Remote Server Sync to copy the newly uploaded files to a folder that is not on a remote server.

Testing Tools

There are many free services available for testing Webhooks. RequestBin.com gives you a URL that collects requests you send it so you can inspect them in a human-friendly way. PipeDream gives you a URL that will collect requests made to it and let you inspect them in a human-friendly way. localtunnel will assign you a unique publicly accessible url that will proxy all requests to your locally running web server. Zapier can create a "Zap" to turn webhook messages into emails, or process them with another service.

Failed Tests

If you use the web interface to save your new webhook, a test message will be automatically sent to the address. Each URL in the webhook must return any HTTP status code between 200 and 299 to indicate success. Any other response code will be treated as a failure.

When a test message sent by the web interface fails, the error that was generated will be displayed, and the webhook will not be saved. You can choose to override the test failure and save the webhook anyway.

Saving the webhook configuration through any other interface, such as the CLI or any of the official FIles.com SDKs, does not automatically trigger this test. You can replicate this feature by using the Test Webhook functionality.

Zapier

Many customers of ours who are also Zapier customers will use the Webhooks by Zapier trigger to receive webhooks from Files.com and trigger Zapier actions based on that. This allows the ability to create custom webhook handlers and actions without requiring extensive programming knowledge. In addition, this webhook handler will allow you to filter incoming webhooks to specific actions (ie: only send a special notification email when a specific file is deleted). This usage of Zapier is not technically part of our Zapier app or integration, but it works just fine and we are happy to support it.

Inbound Webhooks

This article is about Files.com sending outbound Webhooks to an external webhook listener, either one hosted by you or through another service, such as Zapier. A related but separate feature is Files.com's ability to trigger an Automation when an inbound webhook message is received.

Expansion of Webhook Capabilities

Are there additional things you would like to see Webhooks for? We're interested to hear about how additional Webhook functionality would meet your business needs. Please feel free to contact us with any feature requests for Webhooks.