Rules & Ruleset
What are rules?
Rules define additional logic to apply to a
Connection to give you control of the behavior of your webhooks.
Each rule is a type associated with its behavior on a set of parameters. Rules can be applied either on a connection or through a ruleset.
- Alert Strategy
- Automatic Retry
- Connection Filters
Hookdeck is planning on releasing new rules in the near future (ex: transformation of payload). Mastering Ruleset and Rules will be a game changer in taking control of your webhooks!
What is a Ruleset?
Ruleset is a set of rules defined by the user that can be reused on multiple webhook connections.
A ruleset can contain and is a combination of a retry logic, an alert logic and/or filters.
Ruleset is the parent element, and
Custom Ruleset is a child element of rules. When you apply a Custom Rule, it will override the
Ruleset rules and apply the Custom Rule instead.
What are Custom Rules?
Custom Rule is a rule directly applied to a
Custom Rule will always take precedence over a
Ruleset rule in case of overlap of rule types.
Suppose you always want the same alert strategy across all your webhook connections. In that case, we recommend making it part of a Ruleset and setting more specific rules to your webhook connection as a Custom Rule.
Receiving alerts in a timely manner results in a more proactive approach to troubleshooting. You no longer need to wait for customer support to report an issue to be aware of a problem that has impacted the client.
The alert logic is composed of two elements:
- The Alert Strategy determines when Hookdeck's will send you alerts for failed events.
- Each Attempt Failure: Send an alert as soon as an attempt fails.
- Last Attempt Failure: Send an alert when the maximum retry count is reached, and all previous attempts failed.
- The Alert Interval is the time interval between each alert.
Alerts are bound to a single webhook connection. You will receive multiple alerts from Hookdeck within the same time interval if you have failed events from different webhook connections.
The alerts contain the payload of the failed webhook and, by default, will be sent to the emails of each member of the workspace. However, you also have the option to receive webhooks.
To enable webhook alert notifications, head over to your Workspace Setting tab. In the Alert Settings section, toggle enable webhook alert notification and add your
Source to indicate which
Connection will receive the notifications.
In this scenario, Hookdeck takes advantage of its
Source is Hookdeck, and the Destinations are the webhook endpoint that will consume the webhooks.
Automatic Retry Rule
Hookdeck is committed to making sure you can recover from errors. By controlling the retry logic means you can specify what works best for your use cases. Thus, you no longer have to rely on every API provider's different retry logic!
The retry logic is composed of 3 elements:
- The Retry Strategy is an algorithm used to schedule retries. The options are
linearretry will schedule retries with the same delay between each retry. If your interval is 1 hour, then the retries will be every hour.
exponentialretry will progress backoff between retries. Each retry delay will be twice as long as the previous. If your interval is 1 hour, the retries will be 1 hour later, 2 hours later, 4 hours later, 8 hours, etc.
- The Retry Count is the number of automatic retries the event will attempt when there's a failure. The automatic retry stops when there's a successful event.
- The Retry Interval is the time interval between each one of the automatic retries.
The maximum delay for a retry is one week. You will get an error if your configuration leads to a retry schedule that would go over the limit.
Connection Filter Rule
You can set filters to route webhooks based on
For more information, you can read our in-depth section on
Set up a Ruleset
Create a Ruleset
A ruleset can be created while creating a new connection:
Edit a Ruleset
You can edit a
Ruleset by either:
- Selecting the
Rulesetedit button from the connection sidebar
- Selecting the Resource button and finding the ruleset you want to edit
Editing a Ruleset retry strategy will only impact future event attempts. The currently scheduled next attempt time on any given event won't change until that next attempt is made.
Archive a Ruleset
You have the option to archive a ruleset you do not use anymore.
You can only archive Rulesets that are not linked with any webhook connections.
Unarchive a Ruleset
You can unarchive a Ruleset if you decide to want to use it again.
Set up Custom Rules
Add a Custom Rule
Click on the connection you want to add a custom rule. Then select
Select the rules you want to add. In this image, we decided to add a
Custom Rule for the Retry and Alert, thus overriding the existing logic from the
Remove a Custom Rule
To remove a
Custom Rule, click the Delete icon and then Save.