Event Notifications Plugins

Event Notifications are responsible for sending information about events to external systems, such as sending an email, push notifications, opening tickets, writing to chat systems, and so forth.

They receive the event they were triggered for as well as a context object with additional metadata. Each notification consists of two classes. A configuration class, keeping parameters for the notification, and a second class with the actual notification code.

Class Overview

The interfaces to implement are org.graylog.events.notifications.EventNotificationConfig and org.graylog.events.notifications.EventNotification. Both classes are used to register a new notification type via the PluginModule class:

Copy 
addNotificationType(TYPE_NAME,
                    EventNotificationConfig.class,
                    EventNotification.class,
                    EventNotification.Factory.class);

Example Event Notification

You can use the built-in notifications as full examples one for a configuration class and one for a notification class.

To create an event notification plugin start by implementing the EventNotificationConfig interface:

Copy 
public abstract class HTTPEventNotificationConfig implements EventNotificationConfig

Every notification has a unique type name. Usually a string appended by a version number, e.g.:

Copy 
public static final String TYPE_NAME = "http-notification-v1"

Continue with the parameters that are needed for the notification. For example for a HTTP notification a URL is needed:

Copy 
private static final String FIELD_URL = "url";

@JsonProperty(FIELD_URL)
public abstract String url();

A builder for the configuration class is needed:

Copy 
public static Builder builder() {
      return Builder.create();
}

@AutoValue.Builder
public static abstract class Builder implements EventNotificationConfig.Builder<Builder> {
  @JsonCreator
  public static Builder create() {
    return new AutoValue_HTTPEventNotificationConfig.Builder()
                                                    .type(TYPE_NAME);
    }

    @JsonProperty(FIELD_URL)
    public abstract Builder url(String url);

    public abstract HTTPEventNotificationConfig build();
}

Additionally interface methods are to implement:

public JobTriggerData toJobTriggerData(EventDto dto)

This is called when the scheduler executes the notification and is gathering data for the job:

public ValidationResult validate()

On the API level, inputs should be validated, so put the checks here:

public EventNotificationConfigEntity toContentPackEntity(EntityDescriptorIds entityDescriptorIds)

If content pack support is desired, this method is called transferring a notification to a content pack entity.

Take a look at the examples for more details on this.

After creating the configuration class, the actual notification code can be written. This is done by implementing the EventNotification interface in a new class:

Copy 
public class HTTPEventNotification implements EventNotification

There is just a single method to override. The notification logic goes into execute(EventNotificationContext ctx).

The context object is keeping data about the event that lead to the notification; see this class for more information.

For getting a backlog of messages that were the source of the event itself, a service is provided:

Copy 
ImmutableList<MessageSummary> backlog = notificationCallbackService.getBacklogForEvent(ctx)

User Interface

Event notifications need to provide some UI components that let the user enter notification details in a form and also display a summary of the notification in the Event Definition summary.

First of all, event notifications need to register a plugin for eventNotificationTypes. As an example, we will show the definition of the HTTP notification type:

Copy 
eventNotificationTypes: [
  {
    type: 'http-notification-v1',
    displayName: 'HTTP Notification',
    formComponent: HttpNotificationForm,
    summaryComponent: HttpNotificationSummary,
    defaultConfig: {
        url: '',
    },
  }
]

Here is a description of each field the notification needs to provide:

  • type Unique type identifying the notification . You should use the same type as used in the server class.
  • displayName Human readable short name that describes the notification . It will be used in select inputs.
  • formComponent React component providing the form elements the user should fill in order to create the event notification.
  • defaultConfig Object including the default configuration that is used once the notification type is selected. We recommend defining the default configuration in your formComponent and then simply add a reference to it here.
  • summaryComponent React component displaying a summary of the event notification.

In order to help you write the required react components, we now describe what props they will receive and what is expected from the given components.

Form Component

This component should present inputs that need to be filled out in order to configure the event notification. The component will receive the following props:

Copy 
config: PropTypes.object
onChange: PropTypes.func
validation: PropTypes.object
  • config Contains the current configuration the user gave for the notification. This will be set by default to the object given as defaultConfig in the plugin definition.
  • onChange Function to call when an input changes. The function expects to receive the complete configuration object as first argument. Please remember you should not directly modify the config prop, but instead clone the object first and apply modifications there.
  • validation Contains an object with validation information. The object has the following structure:
Copy 
validation: {
  errors: {
    url: [
      "HTTP Notification URL cannot be empty."
    ],
  },
  failed: true
}

When you are done configuring the event notification, Graylog submits the defined configuration into the server and creates the notification.

Summary Component

This component should render a summary of all options configured in the event notification. It will be displayed in the summary step of the event definition form. The component receives the following props:

Copy 
type: PropTypes.string,
notification: PropTypes.object,
definitionNotification: PropTypes.object,
  • type Contains the displayName property defined in the notification plugin.
  • notification Contains the notification object, including its configuration.
  • definitionNotification Contains the notification_id used by the event definition. This is only required in case the Notification plugin is not installed or was deleted.

In order to follow the same style as other notifications in the summary component, we highly recommend using the CommonNotificationSummary component to render all common properties all notifications have: title, type, description, and the children you pass. The component receives the same props as this one, plus the children you want to render with the custom plugin configuration. As an example, this is how the HttpNotificationSummary renders its summary:

Copy 
<CommonNotificationSummary {...this.props}>
  <React.Fragment>
    <tr>
      <td>URL</td>
      <td><code>{notification.config.url}</code></td>
    </tr>
  </React.Fragment>
</CommonNotificationSummary>