Troubleshooting Webhooks

Most webhook delivery issues come from either a bad URL or a receiver script that does not return an HTTP success response (codes 200 through 299) in a timely manner. Your receiver script must return the success response before performing any actual work. Use a delayed job or background job queue to do the work after responding.

Webhook Logs

Site Administrators can access Webhook Logs, which include all the responses received for Webhook requests. To retrieve webhook logs from the Files.com API or the CLI, see the 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 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 response, 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

When a 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. The message "Webhook URL is invalid" 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.

Duplicate Webhook Delivery

When a delivery attempt does not return an HTTP success response in a timely manner, Files.com marks that attempt as failed and retries the request. To avoid timeouts and duplicate deliveries, simplify the receiver script so it returns the success response immediately, and offload the actual work to a delayed job or background job queue.

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 Test is one way to identify common SSL certificate issues.