Webhooks

Need automated alerting when something happens on your Files.com site? Our Webhooks may be for you.

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.

Inbound Webhooks

This article is about Files.com sending outbound Webhooks.

A related but separate feature is Files.com's ability to trigger an Automation when an inbound webhook is received.

Setting up a Webhook

To set up a webhook, go to the folder that represents the root folder you are concerned with receiving notifications about. This can be the site root.

Open the Folder Settings and then click Webhooks > Add new webhook. You'll enter your webhook handler URL and any backup URL(s).

The first webhook URL is the primary URL where you would like us to send our HTTP request, and any backup URLs are redundant webhook URLs that will also be attempted.

Webhook URL requirements

  • 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.
  • When we send a request to your Webhook URL, it must return an HTTP response code of 200.

Customizing webhook triggers

By default, webhooks will trigger for any file or folder action (create, read, update, delete, move, or copy) within the configured folder.

You can limit which actions will trigger webhooks by choosing the Only trigger on specific actions option, and selecting the specific actions that you want to trigger webhooks.

Customizing the HTTP method

By default, webhooks will be sent as HTTP GET requests.

You can customize whether webhooks are sent as an HTTP GET or POST request by clicking Expand advanced settings and selecting the method you want to use.

Adding custom headers

You can add custom HTTP headers to be included with each webhook by clicking Expand advanced settings and adding the header key and value under Headers. Click +Add another header to add additional headers.

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.

To add custom body elements, after clicking Expand advanced settings and selecting the POST method, add the element key and value under Body. Click +Add another body element to add additional body elements.

To customize the encoding of the webhook body, under Encoding select between Standard HTTP POST body, XML, and JSON encodings.

Explanation 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 happening and will include several URL parameters.

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.

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, log in to the web interface as an administrator and navigate to Settings > Logs > Webhook logs.

The most recently logged items will load by default. You can focus on a particular date and time window by clicking on the from and to fields at the top of the list and using the date pickers to adjust the dates and times.

Click the Filters button above and on the right side of the log list to limit the displayed items to those relevant to your purpose. Enter/select the values you would like to filter by and click Update Logs.

To generate an export file, click the Export button (to the right of the Filters button) and select your date range. Click the Download CSV button to generate and download the output file.

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

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.

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.

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