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 very 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 priviledges on the folder. Webhooks can be created via the Folder Settings for that folder under the settings named Webhooks.

Site administrators can access a global listing of configured webhooks for their entire site.

When adding a new Webhook, you must provide the 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.

In addition to a Primary URL, you can also add one ore more Backup URLs. 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 for that Webhook.

The Limit to a specific folder setting will cause the Webhook to only be triggered by actions in the specified folder and its subfolders. This setting is automatically configured with the current folder when navigated to via the Folder Settings. For a webhook that applies to your entire site, either omit the Limit to a specific folder option or select your site's root folder with /

As soon as you save your new Webhook, a test message will be sent to the address. The listener must return any HTTP status code between 200 and 299 to indicate success. Any other response code will be treated as a failure.

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. If you are using the web application to configure your Webhook, and you don't see one of these settings described here, try looking for Advanced Settings

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 only 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; when this is selected, activity for any file will generate a message.

Rather than All files, you can use the Only files matching specific patterns fields to indicate file name rules for 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 will only appear 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 may wish to enable this for simplifying 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 along 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 option to customize the Webhook body encoding is hidden in the web interface if you are sending the contents of the file in the request. This is because the method of 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.

By default, new Webhooks will have their Attach the contents of the triggering file value set to No file contents, and messages generated by the Webhook will not include the file contents.

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 webhook 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.

To verify Webhooks using the EV1 or EV2 body encoding, you'll instead use the x-exavault-signature header. Instead of concatenating the path of the file to the verification token, concatenate the entire request body to the verification token before taking the MD5 of the result.

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.

ExaVault Legacy Format Webhooks

Sites which have been upgraded from an ExaVault account may prefer to use Webhook requests formatted like those sent by the ExaVault legacy platform. Files.com provides two request encoding formats that produce requests designed to be compatible with legacy Webhook listeners.

Creating New ExaVault Format Webhooks

Create a new Webhook for a folder, either within the Folder Settings, or from the Webhooks page, and change the Method setting for your webhook to POST, then change the Encoding to ExaVault legacy format (v1) or ExaVault legacy format (v2)

Webhook Signature Verification

A Webhook that uses an ExaVault legacy format encoding will also include a Verification Token. You may use this token in combination with the x-exavault-signature header to verify that Files.com is the sender of the Webhook request. You will use the same 3-step procedure formerly used for ExaVault webhooks to validate that an individual webhook request was sent by Files.com.

First, locate the verification token in your Webhook settings. Every webhook request sent to your endpoint URL will use the same verification token for that webhook. You can use the Regenerate token button to change the token. You'll concatenate that token along with the raw string representing the request body that was received. The resulting string will be the verification token followed by the contents of the request body. Do not convert the request body to any other type of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. After concatenating the verification token with the request body, calculate the MD5 hash of that concatenation. The resulting hash should match the contents of your x-exavault-signature header.

ExaVault Legacy Format (v1) Request Structure

Messages for webhooks using ExaVault legacy format (v1) contain a JSON-formatted string (not including extra whitespace or line breaks) with the following properties.

Here is a prettified version of a sample ExaVault legacy format v1 request, with added line breaks and whitespace for readability. The actual request body will not contain extra whitespace.

{
  "accountname": "testsite",
  "username": "bob.johnson@example.com",
  "operation": "Download",
  "protocol": "web",
  "path": "/Aboodabha/Pics_2.png",
  "sourcepath": null,
  "attempt": 1,
  "attemptId": "1df19v0v-1"
}

ExaVault Legacy Format (v2) Request Structure

Messages for webhooks using ExaVault legacy format (v2) contain a JSON-formatted string (not including extra whitespace or line breaks) with the following properties.

The eventData.resources object contains the following properties

The eventData.destinationResource object, which is only included for the resources.copy or resources.move event, contains the following properties.

Here is a prettified version of a sample ExaVault legacy format v2 request, with added line breaks and whitespace for readability. The request you receive will not contain any extra whitespace.

{
  "attemptId": "1dfj1pgm-1",
  "accountName": "testsite",
  "eventTimestamp": "2023-04-17T15:41:52-04:00",
  "ipAddress": "34.211.45.99",
  "protocol": "web",
  "username": "bob.johnson@example.com",
  "event": "resources.upload",
  "eventData": {
    "resources": {
      "id": 6541587968,
      "hash": "11111111111111111111111111111111",
      "name": "Files.docx",
      "extension": "docx",
      "type": "file",
      "createdBy": "bob.johnson@example.com",
      "uploadDate": "2023-04-17T15:41:52-04:00",
      "createdAt": "2023-04-17T15:41:52-04:00",
      "updatedAt": "2023-04-17T15:41:52-04:00",
      "accessedAt": null,
      "path": "/Uploads/Files.docx",
      "size": 14252,
      "fileCount": null,
      "previewable": true
    }
  }
}

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.

Verifying Webhook Authenticity

Files.com does not cryptographically sign Webhook calls, but this is a commonly requested feature that we plan to support in the future. In the meantime, 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.

Logs

Site administrators can view logging of all the responses received for Webhook requests. Type "Webhook logs" in the search bar at the top of every screen and click on the matching result. To retrieve webhook logs from the Files.com API or the CLI, see our documentation on Action Notification Exports and Action Notification Export Results

Troubleshooting Webhook Issues

Most issues with Webhook delivery relate to either a bad URL or the script at the URL endpoint not returning an HTTP success response (codes 200 through 299) response in a timely manner. Your receiver script should not attempt to perform any actual work prior to returning the HTTP response. You can use a delayed job or background job queue for the actual performance of work.

"Webhook URL is disabled due to having several recent failures" Error in Logs

If attempts to deliver a webhook to your URL repeatedly fail because the URL is unreachable or fails to return a success HTTP response, we will add that URL to a temporary blacklist to prevent further failed delivery attempts. This is done to prevent us from taking down a potentially unstable server by sending it requests it might not be able to accommodate.

After a short period of time (currently 5 minutes), the URL is automatically removed from the temporary blacklist, and webhook delivery attempts resume. Any webhook requests that were not sent due to temporary URL blacklisting will be tried again a few times over 3 days. We will notify you by email if a failure persists beyond that period.

If you see this message in the webhook logs, we recommend double checking your Webhook receiver to ensure that it always quickly returns a success HTTP response (codes 200 through 299). We recommend simplifying your receiver script to perform any actual work prior to returning the HTTP success response. You can use a delayed job or background job queue for the actual performance of work.

"Webhook URL is invalid" Error in Logs

When the URL for a webhook resolves to an invalid hostname (such as example.com) or an invalid IP address (such as a private IP address in the 192.168.x.x or 10.x.x.x ranges), Files.com will not attempt to send messages to that webhook listener. You will see the message "Webhook URL is invalid" in your webhook logs.

Your webhook cannot use any URL that is not publicly available and valid. To resolve this error, supply a URL for a host that can be reached by public internet traffic.

Duplicate Webhook Delivery

If attempts to deliver requests to the URL fail to return a HTTP success response in a timely manner, we will mark that attempt as failed and attempt to deliver the request again. To avoid potential timeouts or duplicate deliveries, we recommend simplifying your receiver script to immediately return the HTTP success response. You can use a delayed job or background job queue for the actual performance of work.

OpenSSL Error While Adding a Webhook

If you are receiving an "openssl error" when adding your Webhook, this indicates that there is a problem with the SSL certificate used by the server that hosts your webhook handler. We recommend checking that server's certificate to ensure it is valid. The Qualys SSL Server Test is one easy way to identify common issues with a site's SSL certificate.

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.

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 your 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.