User > Subscribe to events > How to use subscriptions

How to use subscriptions

In xMatters, you can use subscriptions to ensure that you are always informed about certain events. Depending on your permissions and the configuration of your deployment, you can set up subscriptions with specific criteria, or be added to event feeds by a supervisor. These subscriptions will send you notifications whenever an event occurs that matches your criteria, even if you are not scheduled to receive a notification for that event; for example:

  • The manager of a network administration team wants to receive an email whenever an outage occurs on a particularly problematic server so she can create a record of these events.
  • The manager of the produce department in a grocery store wants to know every time an issue is reported with a refrigeration unit anywhere in the store, even if the issue is not occurring in her area.
  • The supervisor for the fuel depot at an airport wants everyone on his team to be notified whenever a supply shortage is reported, even if they are not on shift at the time of the shortage.

How subscriptions work

Events are usually injected into xMatters from an external system or application, though some events can also be initiated by xMatters itself. xMatters identifies each source, and differentiates it from other sources, based on the properties contained within the event. xMatters then creates and sends notifications to the appropriate personnel, and processes the responses.

A subscription form, usually created by a communication plan designer, acts as a filter on events from a particular source. The subscription form designer can specify:

  • Which form properties are available to use when specifying a subscription's criteria
  • Which users (or roles) can subscribe to the form
  • Whether other users can be assigned to the subscription
  • Which devices can receive the subscription notifications

This means that the information you can use to subscribe to events may be entirely different for each subscription form — even ones based on the same communication plan.


Let's say that you work for a major general goods retailer, and you have designed a communication plan to handle events that are injected into xMatters by the software on the loading dock. The plan and its forms use the information in the event to determine the particulars of each incoming delivery and notify the people on shift in each department to let them know that a shipment has arrived. But some of your users want to know about certain deliveries even when they aren't on shift. So you design a subscription system that will send people notifications based on the properties of the event. Here's how that system might work:

In the above illustration, a delivery of seafood arrives at the loading dock, and an event is injected into xMatters that triggers the communication plan. xMatters processes the event, and then creates and sends notifications to the appropriate targeted and on-call recipients.

The communication plan has two subscription forms: one for groceries (or perishables), and another for clothing. The delivery contains the grocery property, and xMatters checks for subscriptions based on the groceries form. There is an active subscription based on seafood, so xMatters sends a notification to the subscribers that a seafood delivery has arrived.

How subscription responses work

Subscription notifications can be one-way (FYI) notifications, or they can include the same response options defined on the communication plan form for targeted notifications. These response choices have the same effects on the originating event as response actions configured for targeted notifications, meaning that they will still record the response, assign ownership to the responder, or end the event.

To aid in the design and implementation of some specific integrations that rely on subscriptions as the main notification delivery mechanism, xMatters treats subscription notifications and targeted notifications as separate entities with respect to escalation management. What this means is that a response to a subscription notification will not affect the group escalation process for targeted notifications sent for the same event.

For example, imagine that an event entering the system generates two notifications: a targeted notification sent to the Operations group which has a five minute delay between members, and a responses-enabled subscription notification sent to Mary McBride. The first Operations group member on the schedule does not respond, but Mary responds to her subscription notification with "Assign to User", effectively taking ownership of the event. Because subscription and targeted notifications are separate streams, however, the escalation for the Operations group continues, and the second member is notified five minutes later. The same would also be true if the subscription notification was sent to the Operations group, and Mary responded to a targeted notification. (The exception to the continued escalation behavior is the "End" response action, as this would effectively terminate the event for all recipients.)

To avoid this situation, make sure that everyone who may need to take specific actions on events for a particular form is receiving either targeted or subscription notifications, but not both. In the case where users and groups are all receiving targeted notifications, for example, you may want to configure your subscriptions as one-way, and not enable responses at all.

Subscription sources

The subscriptions you can create in your deployment depend on the configuration of your system, and on the event feeds configured by your administrator. In some cases, you may be able to subscribe to event feeds but not view the details or the criteria they are using; for other subscriptions, you might not be able to unsubscribe, but still able to control when it sends you notifications. You may also be able to share your subscriptions with other users, and set the permissions they have to act on your subscriptions.

There are two ways to subscribe to events in xMatters, depending on the event source:

  • Subscription forms are based on communication plans, and created and configured by a forms designer.
  • Subscription domains are based on event domains, which identify the external applications that can inject events into xMatters.

The Subscriptions page treats both types of subscription equally, and does not indicate whether a subscription is based on an external application (subscription domain) or a communication plan (subscription form). The only difference apparent to subscribers is which options are available on the Subscription Details page when viewing each subscription.