<commit_before>---
title: Custom notification and alerting using ServiceControl events
summary: How to build a custom notification by subscribing to ServiceControl events
tags:
- ServiceControl
- ServicePulse
- Notifications
redirects:
- servicepulse/custom-notification-and-alerting-using-servicecontol-events
---


## Custom notification and alerting using ServiceControl events

ServiceControl events allow to build notifications/integrations that will alert of something going wrong in your system.

ServiceControl's endpoint plugins collect information from monitored NServiceBus endpoints. For more information see [ServiceControl Endpoint Plugins](/servicecontrol/plugins/).


### Alerting on FailedMessages Event

Once a message ends up in the error queue ServiceControl will publish a `MessageFailed` event. As you can see the message contains enough context to help identify the cause of the error, the endpoint, the time, the stack trace and more. if you need more information you can call ServiceControl's HTTP API.


### Subscribing to ServiceControl Events 

ServiceControl publishes `MessageFailed` event when a message gets to the error queue, let's see how we can tap in by subscribing to these events and act on them (send an email, pager duty and so on).

To subscribe to the `MessageFailed` event:
- Create an [NServiceBus endpoint](/nservicebus/hosting/nservicebus-host/)
- Install the `ServiceControl.Contracts` [nuget package](https://www.nuget.org/packages/ServiceControl.Contracts/).
- Add the message mapping in the `UnicastBusConfig` section of the endpoint's app.config so that this endpoint will subscribe to the events from ServiceControl as shown:

<!-- import ServiceControlEventsXmlConfig -->

- Customize the endpoint configuration to use `JsonSerializer` as the message published by ServiceControl uses Json serialization
- Also customize the endpoint configuration such that the following conventions are used, as the `MessageFailed` event that is published by ServiceControl does not derive from `IEvent`. 
The code sample to do both customizations is as shown below:

<!-- import ServiceControlEventsConfig -->

- The endpoint will also need a message handler, that handles the `MessageFailed` event. In the following example, there is also a simple HTTP call to HipChat's API to show how you could integrate with a 3rd party system to provide notification of the error.

<!-- import MessageFailedHandler -->


### Common information contained in events

Both heartbeat and custom check events contain identifying information about the host and the endpoint.


### Alerting on HeartbeatStopped Event

Heartbeats are used to track endpoints health see [this intro for more information](/servicepulse/intro-endpoints-heartbeats.md#active-vs-inactive-endpoints)

Once an endpoint stops sending heartbeats to ServiceControl queue ServiceControl will publish a `HeartbeatStopped` event. 

The message contains the time it was detected and the last heartbeat time.

Similarly to the code above you can subscribe to the event, handle it, and perform custom actions.


### Alerting on HeartbeatRestored Event

Once an endpoint resumes sending heartbeats to ServiceControl queue ServiceControl will publish a `HeartbeatRestored` event. 

The event contains the time the heartbeat was restored.

Similarly to the code above you can subscribe to the event, handle it and provide custom actions.


### Alerting on CustomCheckFailed Event

Custom checks are used to alert OPS of possible issues with third parties see [this intro for more information](/servicepulse/intro-endpoints-custom-checks.md)

Once a custom check fails ServiceControl will publish a `CustomCheckFailed` event. 

The message contains the time it was detected and the failure reason.

Similarly to the code above you can subscribe to the event, handle it and provide custom actions.


### Alerting on CustomCheckSucceeded Event

Once a custom check succeeds ServiceControl will publish a `CustomCheckSucceeded` event. 

The message contains the time it was detected.

Similarly to the code above you can subscribe to the event, handle it, and perform custom actions.


## Decommissioning alert subscribers

ServiceControl uses [Event Publishing](/nservicebus/messaging/publish-subscribe/) to send alerts to all subscribers. If you are using a [persistence based transport](/nservicebus/messaging/publish-subscribe/#mechanics-persistence-based) then ServiceControl will keep an internal reference to each subscriber. If a subscriber for an alert cannot be contacted then ServiceControl will shut itself down after a few attempts.

To prevent this situation it is important to properly decommission an endpoint that subscribes to ServiceControl events. To do this you should [disable auto-subscription](/nservicebus/messaging/publish-subscribe/controlling-what-is-subscribed.md#disabling-auto-subscription) and then [unsubscribe to all events](/nservicebus/messaging/publish-subscribe/controlling-what-is-subscribed.md#how-to-manually-subscribe-to-a-message). This should be done from the endpoint being decommissioned.<commit_msg>remove redundant sentence<commit_after>---
title: Custom notification and alerting using ServiceControl events
summary: How to build a custom notification by subscribing to ServiceControl events
tags:
- ServiceControl
- ServicePulse
- Notifications
redirects:
- servicepulse/custom-notification-and-alerting-using-servicecontol-events
---


## Custom notification and alerting using ServiceControl events

ServiceControl events allow to build notifications/integrations that will alert of something going wrong in your system.

ServiceControl's endpoint plugins collect information from monitored NServiceBus endpoints. For more information see [ServiceControl Endpoint Plugins](/servicecontrol/plugins/).


### Alerting on FailedMessages Event

Once a message ends up in the error queue ServiceControl will publish a `MessageFailed` event. As you can see the message contains enough context to help identify the cause of the error, the endpoint, the time, the stack trace and more. if you need more information you can call ServiceControl's HTTP API.


### Subscribing to ServiceControl Events 

ServiceControl publishes `MessageFailed` event when a message gets to the error queue, let's see how we can tap in by subscribing to these events and act on them (send an email, pager duty and so on).

To subscribe to the `MessageFailed` event:
- Create an [NServiceBus endpoint](/nservicebus/hosting/nservicebus-host/)
- Install the `ServiceControl.Contracts` [nuget package](https://www.nuget.org/packages/ServiceControl.Contracts/).
- Add the message mapping in the `UnicastBusConfig` section of the endpoint's app.config so that this endpoint will subscribe to the events from ServiceControl as shown:

<!-- import ServiceControlEventsXmlConfig -->

- Customize the endpoint configuration to use `JsonSerializer` as the message published by ServiceControl uses Json serialization
- Also customize the endpoint configuration such that the following conventions are used, as the `MessageFailed` event that is published by ServiceControl does not derive from `IEvent`. 
The code sample to do both customizations is as shown below:

<!-- import ServiceControlEventsConfig -->

- The endpoint will also need a message handler, that handles the `MessageFailed` event. In the following example, there is also a simple HTTP call to HipChat's API to show how you could integrate with a 3rd party system to provide notification of the error.

<!-- import MessageFailedHandler -->


### Common information contained in events

Both heartbeat and custom check events contain identifying information about the host and the endpoint.


### Alerting on HeartbeatStopped Event

Heartbeats are used to track endpoints health see [this intro for more information](/servicepulse/intro-endpoints-heartbeats.md#active-vs-inactive-endpoints)

Once an endpoint stops sending heartbeats to ServiceControl queue ServiceControl will publish a `HeartbeatStopped` event. 

The message contains the time it was detected and the last heartbeat time.

Similarly to the code above you can subscribe to the event, handle it, and perform custom actions.


### Alerting on HeartbeatRestored Event

Once an endpoint resumes sending heartbeats to ServiceControl queue ServiceControl will publish a `HeartbeatRestored` event. 

The event contains the time the heartbeat was restored.

Similarly to the code above you can subscribe to the event, handle it and provide custom actions.


### Alerting on CustomCheckFailed Event

Custom checks are used to alert OPS of possible issues with third parties see [this intro for more information](/servicepulse/intro-endpoints-custom-checks.md)

Once a custom check fails ServiceControl will publish a `CustomCheckFailed` event. 

The message contains the time it was detected and the failure reason.

Similarly to the code above you can subscribe to the event, handle it and provide custom actions.


### Alerting on CustomCheckSucceeded Event

Once a custom check succeeds ServiceControl will publish a `CustomCheckSucceeded` event. 

The message contains the time it was detected.

Similarly to the code above you can subscribe to the event, handle it, and perform custom actions.


## Decommissioning alert subscribers

ServiceControl uses [Event Publishing](/nservicebus/messaging/publish-subscribe/) to send alerts to all subscribers. If you are using a [persistence based transport](/nservicebus/messaging/publish-subscribe/#mechanics-persistence-based) then ServiceControl will keep an internal reference to each subscriber. If a subscriber for an alert cannot be contacted then ServiceControl will shut itself down after a few attempts.

To prevent this situation it is important to properly decommission an endpoint that subscribes to ServiceControl events. To do this you should [disable auto-subscription](/nservicebus/messaging/publish-subscribe/controlling-what-is-subscribed.md#disabling-auto-subscription) and then [unsubscribe to all events](/nservicebus/messaging/publish-subscribe/controlling-what-is-subscribed.md#how-to-manually-subscribe-to-a-message).
{'fraction_non_alphanumeric': 0.052626421011368094, 'fraction_numerical': 0.0001960015680125441, 'mean_word_length': 5.121775644871025, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 2, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2895456', 'n_tokens_mistral': 2477, 'n_tokens_neox': 2329, 'n_words': 1242}