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.

URL Validation Errors When Saving

Creating a webhook or changing its configuration validates every primary and backup URL. This applies to the API, CLI, SDKs, and web interface in every Workspace. The API returns an HTTP 422 model validation error on value if any URL is malformed, uses a disallowed port, has a hostname that cannot resolve, or resolves to a private, loopback, or link-local address.

Check every configured URL against the destination URL requirements, including backup URLs. If validation cannot finish, the save fails and an existing webhook keeps its previous configuration. URL validation does not send a test HTTP request or require the receiver to return a successful response.

"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 a failed delivery test only if every URL passes destination URL validation. This is useful when the receiver is temporarily unavailable or not yet ready to return a success response. Its hostname must already resolve to a permitted public address. The override cannot save an unresolved hostname, malformed URL, disallowed port, or private, loopback, or link-local destination.

"Webhook URL is disabled due to having several recent failures" Error in Logs

This message means delivery to the URL is temporarily paused after a connection failure. The pause expires automatically after five minutes, and pending requests follow the webhook retry policy.

Review the delivery errors immediately before the pause to identify the connection problem, such as a refused connection or timeout. Confirm that the receiver is reachable from Files.com and returns a success response promptly. A receiver that accepts the connection but spends too long processing the request can time out before sending its response.

The failure records used for retry processing have a three-day retention period. They can be replaced or removed earlier as retries are processed. These temporary records are separate from the Webhook Logs, which record the requests and responses for delivery attempts.

If processing time is causing timeouts, have the receiver acknowledge receipt with an HTTP success response (codes 200 through 299) and queue the remaining work. After correcting the connection problem, check a subsequent delivery attempt for a successful response; the pause expiring does not by itself confirm that the receiver has recovered.

"Webhook URL is invalid" Error in Logs

The error Webhook URL is invalid means the destination did not pass the URL checks performed when sending. A saved URL can fail these checks later, for example if its hostname stops resolving or resolves to a private, loopback, or link-local address. Files.com does not attempt to send messages to that webhook listener. This error appears in your Webhook Logs.

A URL that works in your browser may still be unreachable from Files.com's servers, which initiate the webhook connection. Supply a publicly reachable endpoint that meets the webhook URL requirements.

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.