Webhook best practices

Modified on Fri, 14 Jun at 12:51 PM


Subscribe to the minimum number of events


You should only subscribe to the webhook events that you need. This will reduce the amount of work your server needs to do.  For more infomation on subscribing to events, see How to configure Webooks to Fluid Boards integration



Use a webhook secret


You should set a webhook secret for your webhook and verify that the signature of each webhook delivery matches the secret. This helps to ensure that the webhook delivery is from Fluid. For more information, see Validating Webhooks


The webhook secret should be a random string of text with high entropy. You should securely store your webhook secret in a way that your server can access.



Use HTTPS and SSL verification


You should ensure that your server uses an HTTPS connection. By default, Fluid will verify SSL certificates when delivering webhooks. Fluid recommends that you leave SSL verification enabled.



Allow Fluid's IP addresses

You can set up an IP allow list for your server, and add the IP addresses that Fluid uses for webhook deliveries. This can block spoofed requests to your server. Reach out to your customer success representative for list of Fluid IPs for your specific instances.



Respond within 10 seconds

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 (Java).


Failed deliveries are retried every every hour (approx) until the webhook event itself expires which is within 24 hours or until a 2XX response is received.



Check the event type and action before processing the event


There are multiple webhook event types, and many events can have multiple action types. Fluid continues to add new event types and new actions to existing event types. Your application should check the event type and action of a webhook payload before processing the payload. To determine the entity type, you can use the X-Fluid-Entity request header. To determine the action type, you can use the X-Fluid-Event request header or top-level event key in the event payload.



Use the X-Fluid-Delivery header


In a replay attack, a bad actor intercepts a webhook delivery and re-sends the delivery. To protect against replay attacks, you can use the X-Fluid-Delivery header to ensure that each delivery is unique.


In the event of a redelivery, the X-Fluid-Delivery header value will be the same as the original delivery






Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select at least one of the reasons
CAPTCHA verification is required.

Feedback sent

We appreciate your effort and will try to fix the article