Subscriptions

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.

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