logo
  • Core Gateway
  • Documentation
  • Blog
  • Pricing
  • About
  • Sign In
    Start your project
Blog
Product Update

Subcriptions Filtering in Convoy

3 min read December 01, 2022

Written by

Raymond Tukpe
Raymond Tukpe

CTO

Share

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:

  • Allowing only events with relevant data to be sent to an endpoint.
  • 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

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

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

Events log showing all four sent events

Event deliveries table showing the three matched 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!

Getting started with Convoy?

Want to add webhooks to your API in minutes? Sign up to get started.

Sign up

Related Posts

What I’ve learned from talking to users as a Technical Founder

April 23, 2025

It’s widely accepted that the two most important things a startup needs to get right are building a great product and talking to users. As a technical founder, building has always come naturally to me. Talking to users? Not so much. In this post, i’ll share some of the misconceptions I had about talking to users—and the surprising benefits I’ve discovered from doing it consistently.

Subomi Oluwalana
Subomi Oluwalana

Co-Founder & CEO

Transactional Outbox: How to reliably generate webhook events

April 17, 2025

In the world of distributed systems, ensuring reliable event delivery is crucial, especially when dealing with webhooks. The transactional outbox pattern has emerged as a robust solution to this challenge. In this post, we'll explore how to implement this pattern to guarantee reliable webhook delivery, even in the face of system failures.

Subomi Oluwalana
Subomi Oluwalana

Co-Founder & CEO

logo

2261 Market Street, San Francisco, CA 94114

Companyaccordion icon

About Us

Trust Center

Terms of Use

Privacy Policy

DPA

Productaccordion icon

Open Source

Core Gateway

Cloud

Convoy Playground

Resourcesaccordion icon

API Reference

Documentation

Status Page

Roadmap

What are Webhooks?

Convoy vs. Internal Implementation

Speak to usaccordion icon

Slack

Follow Us

Copyright 2025, All Rights Reserved

soc stamp