Subscriptions

Learn how to use subscriptions to notify a list of recipients associated with an object in your data model.

Subscriptions are an extension to Objects and express the relationship between a Recipient (the subscriber) and an Object.

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.

How subscriptions work

  1. Identify an object in a collection that represents the topic, or entity you wish to subscribe recipients to
  2. Subscribe one or more recipients to the object by creating a subscription between the recipient and the object
  3. 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.

Integrating subscriptions

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 project-1.

Go to API documentation →

Subscribing recipients to an object

Subscribing a recipient to an object creates an ObjectSubscription entity describing the relationship between the Recipient and the Object.

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.

Unsubscribing recipients from an object

To remove one or more recipients (up to 100) from an object, you can pass a list of recipient identifiers.

Triggering a workflow for all subscribers of an object

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.

Retrieving subscriptions for an object

You can retrieve a paginated list of subscriptions for an object, which will return the recipient subscribed as well.

Retrieving subscriptions for a user

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.

Accessing subscription properties in a workflow run

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 recipient.subscription namespace.

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.

Modeling nested subscription hierarchies

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.

💡
Note: currently we only support subscriptions at a maximum depth of 2, meaning you can model a hierarchy such as parent -> child -> user but no deeper. If you need to support a deeper nesting, please get in touch.

Deduplication by default

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.

Frequently asked questions

What's the maximum number of subscribers I can have against an object?

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.

Can I have nested relationships for my objects?

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

Can I manage subscribers to an object in the dashboard?

Right now, you can only view the subscribers of an object in the dashboard. You can do so under "Objects > Subscriptions".

Can I set custom properties on a Subscription?

Yes, you can pass a set of properties, which is a set of unstructured key-value pairs that you set any arbitrary data about.

Can I filter the set of Subscriptions to be notified?

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.

Can I still debug workflow runs for the subscribers of an object?

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.

Can I notify both the object AND the subscribers of the object?

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.

Can I notify a recipient each time they appear within an object subscription tree?

No, currently Knock deduplicates all recipients when fanning out to object subscribers. If this is blocking one of your use cases or your adoption of Knock, please contact our support team.

Is the object that recipients are subscribed to exposed in the workflow run scope?

No, currently we do not expose the object the subscription belongs to under the workflow run scope.

Will the actor included in the workflow trigger receive a notification if they are a subscriber?

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.