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 Logs

Site administrators can access Webhook Logs, which include of all the responses received for Webhook requests. To retrieve webhook logs from the Files.com API or the CLI, see our documentation on Action Notification Exports and Action Notification Export Results

"We didn't save your webhook" Message in Web Interface

Saving or updating a webhook using the Web Interface will trigger an automatic test webhook message to every URL in your webhook configuration. Each URL that does not return a successful response will display an error, and the webhook will not be saved.

You can choose to override the test failure and save the webhook anyway. If a target URL is temporarily unavailable, you may choose to override the test failure in order to save your settings anyway. You might also do this to prepare for a URL change by adding a backup URL for an address that is not yet available.

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