Event Hooks

Event hooks allow you to extend Obsidian's event notifications to support things like instant messaging, customized logging, etc. This feature was introduced in version 4.5.0.

EventHook Interface

Note: If you need to set up a development environment to create Obsidian event hooks, see the Classpath section.

Implementing custom notifications in Obsidian is as simple as implementing a single interface and calling a method to register it with the scheduler.

The interface you need to implement is the following.

public interface EventHook {
    public abstract void dispatch(Event event) throws Exception;
}

The dispatch() method gets called with every logging/notification event Obsidian encounters. The implementor is responsible for filtering out appropriate events to respond to, and what occurs when an applicable event is encountered. As an example, we've provided a reference implementation of a Slack notifier, and its source code is available in the Obsidian distribution.

For additional information, please refer to the Javadoc for EventHook and the corresponding source code in your Obsidian installation in the file obsidian-builtin-job-src.jar.

Registering your Event Hook

After creating an instance of a class that implements EventHook, you simply need to register it with Obsidian. The example below shows our reference implementation which posts notifications to a Slack channel by using incoming web hooks.

    EventHook customNotifier = new SlackEventHook("Obsidian Scheduler", "https://hooks.slack.com/services/XXXXXXX/YYYYYYYY/ZZZZZZZZZZ", SlackEventHook.DEFAULT_LEVELS, SlackEventHook.Default_CATEGORIES);
    EventHooks.register(customNotifier); // we will now get notifications in Slack for any FATAL, ERROR or WARN events

For additional information, please refer to the Javadoc for EventHooks and the corresponding source code in your Obsidian installation in the file obsidian-builtin-job-src.jar.

Slack Notifier

Obsidian comes with a Slack notifier that can be easily set up by configuring a single configuration property:

com.carfey.obsidian.slack.webhookUrl=https://hooks.slack.com/services/XXXXXXX/YYYYYYYY/ZZZZZZZZZZ

If this property is set, the Slack notifier will automatically be registered with Obsidian on startup.

See Advanced Configuration for full details on configuration options for the Slack notifier.

In addition to the property-based intitalization, you may create your own instance of SlackEventHook and register it as described above. You can choose to create a subclass to customize its behaviour. You may also create multiple instances of the class with different category and level options to further customize when you receive notifications.

REST Endpoint Event Hook

As of Obsidian 5.2.0

Obsidian comes with an Event Hook that can be used to send Obsidian events to a REST endpoint. easily set up by configuring a single configuration property:

com.carfey.obsidian.restfulEventHook.url=https://''myendpoint.com'':1234/rest/obsidian_events

If this property is set, the RESTfulEventHook will automatically be registered with Obsidian on startup.

See Advanced Configuration for full details on configuration options for the REST Endpoint event hook.

In addition to the property-based initialization, you may create your own instance of RESTfulEventHook and register it as described above. You can choose to create a subclass to customize its behaviour. You may also create multiple instances of the class with different category and level options to further customize when you receive notifications.

Standard Output/Error Streams Event Hook

As of Obsidian 5.2.1

Obsidian comes with an Event Hook that can be used to send Obsidian events to Standard Out/Error streams. To enable default behaviour use:

com.carfey.obsidian.standardOutputStreamsEventHook.enabled=true

If this property is set, the StandardOutputStreamsEventHook will automatically be registered with Obsidian on startup.

In addition to the property-based initialization, you may create your own instance of StandardOutputStreamsEventHook and register it as described above. You can choose to create a subclass to customize its behaviour. You may also create multiple instances of the class with different category and level options to further customize when you receive notifications.