Skip to main content

Troubleshooting Webhooks

Most webhook delivery issues come from either a bad URL or a receiver script that does not return an HTTP success responseExternal LinkThis link leads to an external website and will open in a new tab (codes 200 through 299) in a timely manner.

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

Saving or updating a webhook in the Web Interface triggers an automatic test message to every URL in your webhook configuration. Each URL that does not return a successful response displays an error, and the webhook is not saved.

You can override the test failure and save the webhook anyway. This is useful when a target URL is temporarily unavailable, or when preparing 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

When delivery attempts to your URL repeatedly fail because the URL is unreachable or does not return a success HTTP responseExternal LinkThis link leads to an external website and will open in a new tab, Files.com adds that URL to a temporary blacklist to prevent further failed delivery attempts. This protects a potentially unstable server from receiving requests it cannot accommodate.

After 5 minutes, the URL is automatically removed from the temporary blacklist, and webhook delivery attempts resume. Any webhook requests that were not sent during the blacklist period are retried a few times over 3 days. Files.com sends an email notification if a failure persists beyond that period.

If you see this message in the webhook logs, check that your webhook receiver always quickly returns a success HTTP response (codes 200 through 299). Simplify the receiver script so that it returns the success response before performing any work, and offload the actual work to a delayed job or background job queue.

"Webhook URL is invalid" Error in Logs

The error Webhook URL is invalid means the webhook URL 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 does not attempt to send messages to that webhook listener. This error appears in your Webhook Logs.

A webhook URL must be publicly available and valid. To resolve this error, supply a URL for a host that can be reached by public internet traffic.

OpenSSL Error While Adding a Webhook

An "openssl error" when adding a webhook indicates a problem with the SSL certificate on the server that hosts your webhook handler. Check that server's certificate to confirm it is valid. The Qualys SSL Server TestExternal LinkThis link leads to an external website and will open in a new tab is one way to identify common SSL certificate issues.