Troubleshooting webhooks

Missing webhook deliveries

If you are not receiving the webhook deliveries that you expect, you should identify the point at which the delivery is missing.

Trigger an event that you expect to result in a webhook delivery. For example, if your webhook is a Action webhook that is configured on a board, you can create an Action on that board.

1. Wait a few minutes, and then check again. Webhook deliveries can take a few minutes to appear.
2. Make sure that you triggered an event in the location where your webhook is configured. For example, if your webhook is a Action webhook, make sure that you triggered the event in the board where the webhook is configured.
3. Make sure that your webhook is subscribed to the event that you triggered. For example, if you expect a webhook delivery when you create an Action, make sure your webhook is subscribed to the OnCreate Action event.
4. Make sure that your webhook Integration is active. Visit the Webhook configuration and confirm the Active toggle is enabled and set to ON.

Look at the logs for your server. The information in the logs depends on the code that your server runs to handle webhook deliveries. To help you diagnose problems on your server, you may want to add additional log statements to your code.

URL host localhost is not supported

You cannot use http://localhost or http://127.0.0.1 as a webhook URL.

To deliver webhooks to your local server for testing, you can use a http forwarding service. For more information visit  https://ngrok.com/ or https://smee.io/. All examples in our documentation use ngrok for http forwarding.

Failed to connect to host

The failed to connect to host error occurs when Fluid attempts a webhook delivery but could not resolve the webhook's URL to an IP address.

To check whether a host name resolves to an IP address, you can use nslookup. For example, if your payload URL is https://organisation.fluid.work/webhooks, you can run nslookup organisation.fluid.work. If the host name could not be resolved to an IP address, the nslookup command will indicate that the server can't find the host name.

Failed to connect to network

The failed to connect to network error indicates that your server refused the connection when Fluid attempted to deliver a webhook.

You should make sure that your server allows connections from Fluid's IP addresses. You can get your list of Fluid IP addresses by contacting Fluid support or your client success manager.

Timed out

The timed out error indicates that Fluid did not receive a response from your server within 10 seconds of delivering a webhook.

Your server should respond with a Http Response code 2xx within 10 seconds of receiving a webhook delivery. If your server takes longer than that to respond, then Fluid terminates the connection and considers the delivery a failure.

In order to respond in a timely manner, you may want to set up a queue to process webhook payloads asynchronously. Your server can respond when it receives the webhook, and then process the payload in the background without blocking future webhook deliveries. For example, you can use services like Hookdeck or libraries like Resque (Ruby), RQ (Python), or RabbitMQ.

Peer certificate cannot be authenticated with given CA certificates

This error indicates that there is a problem related to your server's certificates. The most common problems are:

• Your server is using a self-signed certificate.
• Your server is not sending the full certificate chain when the connection is established.
• To help diagnose the problem, you can use the SSL server test from SSL Labs. This service can only work with the default port for HTTPS (port 443) and can only work with servers that are accessible from the Internet.

You can also use openssl to help diagnose the problem. To do so, run openssl s_client -connect HOST:PORT in a terminal. Replace HOST with your server's host name and PORT with the port. For example, openssl s_client -connect example.com:443. To identify problems, look for verify error in the output.

Invalid HTTP response

The invalid HTTP response error occurs when your server returns a 4xx or 5xx status in response to a webhook delivery from Fluid.

You should configure your server to return a 2xx status. If your server returns a 4xx or 5xx status, Fluid will record the delivery as a failure.

Webhooks deliveries are out of order

Fluid may deliver webhooks in a different order than the order in which the events took place. If you need to know when the event occurred relative to another event, you should use the timestamps that are included in the delivery payload.

Webhook deliveries are not immediate

Webhook deliveries can take a few minutes to be delivered and to appear in the recent deliveries log. Before concluding that your webhook delivery failed, wait a few minutes and then check again.

Failed signature verification

You should use a webhook secret and the X-Hub-Signature-256 header to verify that a webhook delivery is from Fluid. For more information, see Validating Webhooks

If you are sure that the payload is from Fluid but the signature verification fails:

• Make sure that you have configured a secret for your webhook. The X-Hub-Signature-256 header will not be present if you have not configured a secret for your webhook. For more information about configuring a secret for your webhook, see How to configure Webooks to Fluid Boards integration

• Make sure you are using the correct header. Fluid uses the X-Hub-Signature-256 header, which uses the HMAC-SHA256 algorithm. 

• Make sure you are using the correct webhook secret. If you don't know the value of your webhook secret, you can update your webhook's secret. For more information, see How to configure Webooks to Fluid Boards integration

• Make sure that the payload and headers are not modified before verification. For example, if you use a proxy or load balancer, make sure that the proxy or load balancer does not modify the payload or headers.

• If your language and server implementation specifies a character encoding, ensure that you handle the payload as UTF-8. Webhook payloads can contain unicode characters.