Hello @webhook-consumers,
we’re about to make some improvements to our webhook subscription and delivery stack.
Unfortunately, this will come with small breaking changes in the webhook/notification subscription API.
We’d like to check in with you to learn how you’re impacted so we can plan/time the updates accordingly (and help you migrate, if need be).
[!tip] Webhook delivery payloads will not change
There’s no need to update your receivers. The API change only impacts managing subscriptions.
When should I care?
If you have any tooling in place to manage webhook subscriptions automatically, you’ll need to adjust the API calls your automation makes. Typically, this is either part of your application, or some scripts that are run manually or as part of pipelines.
If you use the notification rules API for managing dashboard, mobile and email notifications, you’re good. We won’t touch these.
[!info] Make your voice be heard
Please feel free to discuss these changes and voice any concerns here the forum. Simply post inQuestions & Answers and we’ll be right with you.
What will change?
Separate subscription management API for webhooks
We will remove webhook subscriptions from the notification rule API and provide a dedicated endpoint for managing them. Our reasoning is, that, while notifications and webhooks share some characteristics (like being event based and subscribed to), these are more technical than logical in nature. API consumers working with webhooks are unlikely to implement the same types of notifications using other channels in parallel.
So as an example, to create a subscription, instead of POSTing a new notification with a webhook payload against /accounts/{accountID}/users/{userID}/notifications/rules, you’ll get a dedicated endpoint for that. The same goes for listing and removing subscriptions.
Subscription scope: User → Account
Currently, webhook subscriptions are scoped to a single user. But this is not how you’d want to use subscriptions: You rather want to receive events for a group of systems, e.g. all the systems you operate, or the ones in a single country or subsidiary, or the ones with a certain feature set enabled.
We reviewed all active subscriptions and found that this is what you are doing: You created technical user accounts on a certain level of your account and use these to subscribe.
Going forward, this workaround will no longer be required: The new API will allow for subscribing on an account level only.
Removal of subscription filters
Currently, the filters property of a notification rule can be used to restrict if notification/webhook deliveries should be carried out based on data within the event triggering it.This feature is not being used by anyone currently.
We decided to discontinue supporting it, as using it is hard to get right and to debug and needs extra care to secure.
What’s next?
We’ll post the API specification draft here as soon as it’s ready and will be happy to discuss the details with you.
This is just the first step in a series of updates to improve our webhook offering. Besides internal changes, we’ll tackle logging/better debugability, better retries and deduplication support as well as managing stale subscriptions in an automated fashion.