Webhooks

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

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 might include:

  • 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

Creating a new webhook always requires two things - the path being monitored by the webhook and the URLs that will receive the webhook messages.

  1. The path of the folder that this webhook is watching. Any folders within that path will also be checked for this webhook activity. The path must be slash-delimited, but it must neither start nor end with a slash. Maximum of 5000 characters.

For a webhook that applies to your entire account use / as your path

  1. the urls indicate what address(es) receive the webhook messages for matching activity. You can specify a single webhook listener address, or an array of addresses. Messages are sent to all of the URLs that you supply.
  • URLs must resolve to public IP addresses. They cannot be internal IP addresses like 192.168.x.x, 10.x.x.x, etc.
  • Ports other than 80, 443, 8080, or 8443 are not allowed.
  • If port 443 is used (SSL), the site must have a valid SSL certificate.

Your Webhook URL must return an HTTP response code of 200

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 file activity triggers setting determines what types of activity send messages to your listener(s).

If you do not supply triggers for your webhook, then any file activity in the folder will cause webhook messages to be sent to your listeners.

You can specify any combination of the allowed trigger types (e.g "create,update,read" will trigger the webhook for all types of uploads and downloads while just read would only trigger for downloads):

Trigger TypeOccurs when...
createWhen a file is uploaded into your folder
readWhen a file is downloaded from your folder
updateWhen a file is updated in your folder
destroyWhen a file is deleted from your folder
moveWhen a file is renamed or moved into your folder
copyWhen a file is copied into your folder

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. Some other settings will cause webhook requests to be sent as a POST request, even if you have set the method to GET with this setting.

If your file names contain sensitive information or PII, we recommend setting your webhooks to use the POST method so that the filenames are not automatically logged by your webhook listener's web host.

Add custom headers to the webhook request

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 also override user-agent header with this setting.
  • When the webhook message 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 the webhook body

If you customize the HTTP method of a webhook to use the POST method, you can optionally add custom elements to be included in the body of webhook requests, as well as customize the encoding of the webhook body.

Valid options for encoding the webhook request body:

EncodingDisplay NameContent-Type
RAWStandard HTTP POST bodyapplication/x-www-form-urlencoded
XMLXMLapplication/xml
JSONJSONapplication/json

Including File Data In Webhook Requests

Your webhook listener will receive the contents of the file that triggered your webhook request when you use the file_as_body setting or the file_form_field setting

The file_as_body setting is a boolean (true/false) field. By default, this will be false

  • When this is set to true the contents of the file that triggered the message are sent as the body of the webhook message request. In addition, the webhook request will be sent using the POST method.
  • When this is set to false, the file contents aren't included as the message request body.

The file_form_field setting accepts a field name that you choose.

  • If this setting is not blank, the webhook will submit a multipart/form-data POST with no request body encoding, and the contents of the file that triggered the webhook request will be included in a field named to match the file_form_field setting.
  • If this setting is left blank, your file contents won't be included in the message request body.

If you enable both the file_as_body setting and the file_form_field setting, the file_form_field setting is ignored.

Structure of the Webhook request

Whenever any file or folder action occurs within a webhook-enabled folder, 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 200 response code.

Request URL Parameter Reference

ParameterExplanation
actionType of action that occurred. Will be one of the following: create, read, update, destroy, move, copy. Renames are treated the same as a move action.
interfaceInterface where the action occurred. Will be one of the following: web, ftp, robot, restapi, sftp, or dav. The robot interface is referenced when a file is acted on by an automated process that occurs on our side. For example, if you had a behavior rule to delete files in a specific folder after 3 days, and the rule was triggered, this would result in a webhook triggering with the action destroy and the interface robot.
pathPath of the file that was operated on.
destinationIf a move or copy action, the new filename.
atTimestamp of the action, format: Y-m-dTH:M:S+00:00.
usernameUsername that performed the action.
typeIndicates whether the action occurred on a file or a directory, when applicable.
sizeSize of the file that was operated on (in bytes).

Expected response code

We expect an HTTP 200 response code, 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.

As a best practice, your webhook listener should return a 200 response as quickly as possible when the request is received. If there is any time-consuming processing to do, the webhook listener should 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 webhooks from IP addresses in our list of published IP Addresses. All Files.com webhook calls will originate from one of these addresses.

Logs

To see webhook logs via the web interface, log in as an administrator and navigate to Settings > Logs > Webhook logs.

For information on how 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 200 response in a timely manner.

We strongly recommend that your webhook receiver script simply act as a message receiving endpoint and not attempt to perform any actual work prior to returning the HTTP 200 response. You can use a delayed job or background job queue for the actual performance of work.

"Webhook URL on temporary blacklist" Error in Logs

If attempts to deliver your webhook to the URL repeatedly fail because the URL is unreachable or fails to return a 200 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 an already 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 webhooks 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 an HTTP 200 response. We recommend simplifying your webhook receiver script to simply act as a message receiving endpoint and not attempt to perform any actual work prior to returning the HTTP 200 response. You can use a delayed job or background job queue for the actual performance of work.

Duplicate Webhook Delivery

If attempts to deliver your webhook to the URL fail to return a HTTP 200 response in a timely manner, we will mark that attempt as failed and attempt to deliver the webhook again. To avoid potential timeouts, we recommend simplifying your webhook receiver script simply act as a message receiving endpoint and not attempt to perform any actual work prior to returning the HTTP 200 response. You can use a delayed job or background job queue for the actual performance of work.

OpenSSL error when 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 the 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.

Testing Tools

For testing webhooks, you might consider using one of the following free services:

  • RequestBin.com gives you a URL that collects requests you send it so you can inspect them in a human-friendly way. Their service can be used to see what your HTTP client is sending or to inspect and debug webhook requests.RequestBin.com provides you with a webhook endpoint (URL) that you can assign to your Files.com folder path. Once there is some activity on your Files.com folder, Files.com sends data about that activity to the RequestBin.com endpoint where you can view the JSON data that would normally be sent to your webhook script.

  • PipeDream - PipeDream gives you a URL that will collect requests made to it and let you inspect them in a human-friendly way.

  • localtunnel - Localtunnel will assign you a unique publicly accessible url that will proxy all requests to your locally running webserver.

  • Zapier - You can create a "Zap" to turn webhooks into emails, or process them with any other service they integrate with.

Zapier

Many customers of ours who are also Zapier customers will leverage 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 is received.

Expansion of Webhook capabilities

Are there additional things you would like to see webhooks for?

We already have the capability to expose webhooks on request for creation/updates/deletes of users, groups, and permissions. We are willing to add more webhooks if there's anything that would be useful for you.

Please feel free to contact us with any feature requests for Webhooks.

Get Instant Access to Files.com and Start Collaborating and Automating

The button below will take you to our Free Trial signup page. Click on the white "Start My Free Trial" button, fill out the short form on the next page, get your account activated instantly, and start setting up your Files and Workflows immediately.

Start My Free Trial