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.

Current Rules:

  • 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?

A 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.

default ruleset

The 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.

Override ruleset

What are Custom Rules?

A Custom Rule is a rule directly applied to a Connection. A Custom Rule will always take precedence over a Ruleset rule in case of overlap of rule types.

Example custom rule

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.

Alert 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.

alert rule

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.

webhook alert notification

In this scenario, Hookdeck takes advantage of its Connectionconcept. The 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 linear and exponential.
    • linear retry will schedule retries with the same delay between each retry. If your interval is 1 hour, then the retries will be every hour.
    • exponential retry 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.

automatic retry rule

Read Tutorial

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 Header, Body, Query, and/or Path.

Create or Update filters

For more information, you can read our in-depth section on Connection Filters

Set up a Ruleset

Create a Ruleset

A ruleset can be created while creating a new connection:

Create a ruleset

Edit a Ruleset

You can edit a Ruleset by either:

  • Selecting the Ruleset edit button from the connection sidebar
  • Selecting the Resource button and finding the ruleset you want to edit

Connection resources
Selecting a ruleset
Edit a ruleset

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.

Archive a Ruleset

Unarchive a Ruleset

You can unarchive a Ruleset if you decide to want to use it again.

Unarchive a Ruleset

Set up Custom Rules

Add a Custom Rule

Click on the connection you want to add a custom rule. Then select Edit.

Edit a connection

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 Ruleset.

Create a custom rule

Remove a Custom Rule

To remove a Custom Rule, click the Delete icon and then Save.

Delete a custom rule