Webhook best practices

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