You can use subscriptions for:
- Creating notifications for a large number of recipients (e.g. all users of your product)
- Alerting use cases, where users can opt into and out of an alert
- Publish/subscribe models where you want to fan out to a set of users subscribed to a topic
Any Object within Knock can be subscribed to by one or more recipients, and the entire set of subscribers can be notified by triggering a workflow for the object, without you needing to keep the relationship data within your system of who is subscribed to what.
- Identify an object in a collection that represents the topic, or entity you wish to subscribe recipients to
- Subscribe one or more recipients to the object by creating a subscription between the recipient and the object
- Trigger a workflow for the object
On step #3, Knock will handle the fan out of the workflow trigger to all recipients that are subscribers, automatically enqueuing a workflow run for the recipient on your behalf.
Note: for all of the examples below you will need to have an object identified within Knock. In our examples below, we create an object under a
project_alerts collection with an id
Subscribing a recipient to an object creates an
ObjectSubscription entity describing the relationship between the
Recipient and the
You can subscribe up to 100 recipients to an object at a time by passing one or more
RecipientIdentifiers. There is no limit to the number of recipients you can subscribe to an object.
Similar to workflow triggers, you can inline identify recipients while subscribing them to an object.
To remove one or more recipients (up to 100) from an object, you can pass a list of recipient identifiers.
By default when you trigger a workflow for an object that has subscriptions attached Knock will fan out to all subscribers and enqueue a new workflow run for that recipient, with the information passed into the workflow trigger.
You can retrieve a paginated list of subscriptions for an object, which will return the
recipient subscribed as well.
You can retrieve a paginated list of active subscriptions for a user, which will return the
object that the user is subscribed to as well.
When triggering a workflow for a recipient from a subscription, the
properties defined on the subscription are made available for use within the workflow run scope. You can access the properties under the
As an example, if you have a property
role under your subscription properties, you can access it as
recipient.subscription.role in the workflow run scope.
It's possible to model nested subscription hierarchies by associating child objects as subscribers of a parent object. This allows you to create structures like "organizations" having many "teams" which have many "team members" (users).
Once you've established a nested hierarchy like the above, it's also possible to notify all child subscribers from a parent object. In the example above, that means we could notify all team members of an organization by setting the recipient of the trigger to be the organization.
parent -> child -> user but no deeper. If you need to support a deeper nesting, please get in touch.
Knock always deduplicates recipients when executing a notification fan out, including for workflow triggers with subscriptions. Knock will ensure your notification workflow is executed only once for each unique recipient in the following cases:
- When the recipient appears both in the initial trigger and as a subscriber to one of your objects.
- When the recipient appears multiple times within a nested subscription hierarchy.
There's no upper bound in the number of subscribers you can have against a recipient, although you can only manage 100 recipients on an object at a time using our API.
Yes! An object with subscribers can also be subscribed to a parent object, allowing you to create nested hierarchies of objects (like a Team has many Projects, and each Project has many Members).
Right now, you can only view the subscribers of an object in the dashboard. You can do so under "Objects > Subscriptions".
Yes, you can pass a set of
properties, which is a set of unstructured key-value pairs that you set any arbitrary data about.
Right now the answer is no, but we're interested in hearing about your use case here as we're considering adding this functionality in the future.
Yes, you can. Once you trigger a workflow for an object that has subscribers attached, you will see a workflow run for each of the subscribers under the "Workflow runs" page.
Yes, by default when you trigger a workflow for an object that has subscriptions attached Knock will generate a workflow run for the object itself AND all of the attached subscribers.
No, currently we do not expose the object the subscription belongs to under the workflow run scope.
No, currently the
actor is always excluded from being a recipient in a workflow trigger, even if they are a subscriber to an object being notified.