Introduction

Subscriptions are conduits through which events are routed from a source to a destination (endpoint) in Convoy. In addition to defining how to deliver events, subscriptions can be used to specify what retry strategy to use, how many times you should receive alerts for failing event attempts and if the subscription should trigger a circuit breaker when an endpoint is returning an error multiple times in a row. They represent the core of event routing for both Incoming and Outgoing events.

Depending on your workloads you would want to intelligently route events to different endpoints based on very specific event payload values or a range of values. Subscription Filters allow you deliver events to endpoints conditionally based on the event’s payload. This can come in handy when both sending and receiving webhooks.

Convoy previously only supported matching events to endpoints using the event types configured on subscriptions, using that alone does not provide enough flexibility that filters do. Additionally filters can be used in addition to event types to offer granularity in the decision of where to send an event to.

The two most common use cases are:

1. Allowing only events with relevant data to be sent to an endpoint.
2. Sending events to different endpoints based on their contents.

Usage

Convoy’s subscription filters utilize a subset of MongoDB’s Extended JSON v2 which supports matching on any value (string, number, boolean, null), nested objects, arrays and some special operators.

How it works

If we are sending events with the payload below, we can create a subscription with a filter which will only send an event to the endpoint when the amount is greater than or equal to 10000.

{
    "provider": "gomoney"
    "amount": 10000
}

{
    "amount": {
        "$gte": 10000
    }
}

We can also filter using the provider field, matching only when it’s set of a range of values

{
    "provider": {
        "$in": [
            "gomoney",
            "piggyvest"
        ]
    }
}

Creating the Subscription filter

Subscription filters are currently available on Convoy Cloud and will ship in our upcoming v0.8 release. By default all subscriptions have a “match all” filter {}. This is essentially like * for the event type field.

Create Subscription form with filter card

After you have added the filter (right side of the image below), you need to add a test payload (left side of the image below) which will be used to validate the payload structure which would be required for the filter to match.

Filter with sample event payload

Testing it out

Now that the filter is set and the subscription is saved you can send test events to validate their behaviour. Create three subscriptions with filters

{
	"amount": {
		"$gt": 100
	}
}

{
	"amount": {
		"$lt": 100
	}
}

{
	"amount": 100
}

Now send some events with the following request bodies

{
    merchant: "xyz stores",
    amount: 100
}

{
    merchant: "xyz stores",
    amount: 1000
}

{
    merchant: "xyz stores",
    amount: 10
}

{
    merchant: "xyz stores"
}

After sending all 4 events, they will all show in the events, but only 3 of them will match the created filters and only 3 event deliveries will be created.

Events log showing all four sent events

Event deliveries table showing the three matched events

Conclusion

Subscription filters are an intuitive way to add granularity when you want to specify the exact endpoints that webhook events should be sent to or when you want to fan out events to multiple endpoints. Convoy gives you the ability to add filters to subscriptions out of the box, without having to add them to your application logic.

Sounds good for your platform? Why not try it out for yourself for free on or cloud and give us feedback on our slack community!