Our webhook API sends an HTTP
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 query string. The API is very easy to use and can be integrated by anyone with server-side programming knowledge.
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.
Setting up a webhook
To set up a webhook, simply go to the folder settings of a folder you would like to assign a webhook to. From there click Webhooks > Add new webhook, and 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
- Ports other than
8443are not allowed.
- If port
443is used (SSL), the site must have a valid SSL certificate.
- Webhook URLs must return an HTTP response code of
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
You can customize whether webhooks are sent as an HTTP
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 requests sent from the webhook API
Whenever any file or folder action occurs within a webhook-enabled folder, an HTTP
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
||Type of action that occurred. Will be one of the following:
||Interface where the action occurred. Will be one of the following:
||Path of the file that was operated on.|
||Timestamp of the action, format:
||Username that performed the action.|
||Indicates whether the action occurred on a
||Size of the file that was operated on (in bytes).|
Troubleshooting webhook issues
The two most common problems with webhook deliverability are providing the wrong webhook URL, and the webhook endpoint not returning an HTTP
A third potential problem you could encounter is your webhook script timing out before Files.com receives the HTTP
200 response. Therefore, if your webhook script performs complex logic or other actions that take time to complete, you may want to have your webhook endpoint immediately return the HTTP
200 status code, and then perform the rest of its actions.
These third-party sites offer troubleshooting tools should you run into issues setting up your Webhooks:
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.
The Qualys SSL Server Test is a free online service that performs a deep analysis of the configuration of any SSL web server on the public Internet.
Many customers will use the Webhooks by Zapier trigger. 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 file is deleted/
Expansion of the webhook API
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 the webhook API.