Splunk® Enterprise

Developing Views and Apps for Splunk Web

Acrobat logo Download manual as PDF

Splunk Enterprise version 7.0 is no longer supported as of October 23, 2019. See the Splunk Software Support Policy for details. For information about upgrading to a supported version, see How to upgrade Splunk Enterprise.
Acrobat logo Download topic as PDF

HipChat example for custom alert actions

The HipChat example implements an alert action that does the following:

  • Posts a message to a HipChat room.
  • Writes log messages to a Splunk Enterprise log file.

When a user selects the HipChat alert actions, the user can select from various actions that are available.

Python file for the HipChat Example

This script has been made cross-compatible with Python 2 and Python 3 using python-future.


from __future__ import print_function
from future import standard_library
import sys, json, urllib.request, urllib.error, urllib.parse

def send_message(settings):
    print("DEBUG Sending message with settings %s" % settings, file=sys.stderr)
    room = settings.get('room')
    auth_token = settings.get('auth_token')
    base_url = settings.get('base_url').rstrip('/')
    fmt = settings.get('format', 'text')
    print("INFO Sending message to hipchat room=%s with format=%s" % (room, fmt), file=sys.stderr)
    url = "%s/room/%s/notification?auth_token=%s" % (
        base_url, urllib.parse.quote(room), urllib.parse.quote(auth_token)
    body = json.dumps(dict(
        color=settings.get('color', "green")
    print('DEBUG Calling url="%s" with body=%s' % (url, body), file=sys.stderr)
    req = urllib.request.Request(url, body, {"Content-Type": "application/json"})
        res = urllib.request.urlopen(req)
        body = res.read()
        print("INFO HipChat server responded with HTTP status=%d" % res.code, file=sys.stderr)
        print("DEBUG HipChat server response: %s" % json.dumps(body), file=sys.stderr)
        return 200 <= res.code < 300
    except urllib.error.HTTPError as e:
        print("ERROR Error sending message: %s" % e, file=sys.stderr)
        return False

if __name__ == "__main__":
    if len(sys.argv) > 1 and sys.argv[1] == "--execute":
        payload = json.loads(sys.stdin.read())
        if not send_message(payload.get('configuration')):
            print("FATAL Failed trying to send room notification", file=sys.stderr)
            print("INFO Room notification successfully sent", file=sys.stderr)
        print("FATAL Unsupported execution mode (expected --execute flag)", file=sys.stderr)

Configuration files for the HipChat example

The HipChat example for custom alert actions contains the following configuration files.

File Description
alert_actions.conf Define the properties of the custom alert action.
app.conf Package and UI information about the add-on.

Required to display information about logger alert actions on the Alert Actions Manager page.

hipchat_alert_icon.png Icon file for the alert action in the Splunk Enterprise UI.
Configuration spec files describing settings in alert_actions.conf and seavedsearches.conf.


alert_action.conf defines the properties of the custom alert action. It also defines parameters to the hipchat.py script.


is_custom = 1
label = HipChat
description = Send HipChat room notifications
icon_path = hipchat_alert_icon.png
payload_format = json

# base URL and Auth token available from your HipChat installation
param.base_url = http://hipchat.splunk.com/v2/
param.auth_token = Hr9marGO3ywwCyZqsE9r91MAMExtFpJKsxCnptbx


Defines properties that appear in the Alert Actions Manager page.

is_visible = 1
label = Mod Alert Tests

author = Splunk
description = Quick examples for testing mod alerts
version = 1.0

state = enabled
is_configured = 1

PNG file for the custom alert action icon

The height and width dimensions of the PNG file should be equal. A PNG files with dimensions of 48x48 pixels works best.


Spec files for the custom alert action

The README directory contains the spec files for custom alert actions.


alert_action.conf.spec describes custom settings for the custom alert action. These settings are used across all instances.



param.base_url = <string>
* HipChat API base URL - adjust if you're using you own server on premise

param.auth_token = <string>
* HipChat OAuth2 token 
* see https://www.hipchat.com/docs/apiv2/auth


savedsearches.conf.spec describes additional savedsearches.conf settings introduced by the custom alert actions. These are per-instance settings.

Reference the parameters listed here with controls in the form that implements the UI for custom actions. See Configure the UI for custom actions.


# HipChat alert settings

action.hipchat = [0|1]
* Enable hipchat notification

action.hipchat.param.room = <string>
* Name of the room to send the notification to
* (required)

action.hipchat.param.message = <string>
* The message to send to the hipchat room. 
* (required)

action.hipchat.param.message_format = [html|text]
* The format of the room notification (optional)
* Default is "html"
* (optional)

action.hipchat.param.color = [red|green|blue|yellow|grey]
* Background color of the room notification (optional)
* (optional)

action.hipchat.param.notify = [1|0]
* Notify users in the room
* Defaults to 0 (not notifying users in the room)
* (optional)

action.hipchat.param.auth_token = <string>
* Override Hipchat API auth token from global alert_actions config
* (optional)

HTML file for the custom alert action form

The HTML file defines the form elements for the custom alert action in the Splunk Enterprise UI.

Highlights of the HTML code:

  • Defines a set of controls to display in the form for the custom action.
  • Uses pre-defined CSS styles to define the controls in the form.
  • Uses {{SPLUNKWEB_URL_PREFIX}} to define paths to local resources. [TBD]


<form class="form-horizontal form-complex">
    <div class="control-group">
        <label class="control-label" for="hipchat_room">Room</label>

        <div class="controls">
            <input type="text" name="action.hipchat.param.room" id="hipchat_room" />
            <span class="help-block">
              The name of a HipChat room.
    <div class="control-group">
        <label class="control-label" for="hipchat_message">Message</label>

        <div class="controls">
            <textarea name="action.hipchat.param.message" id="hipchat_message" />
            <span class="help-block">
                The chat message for the HipChat room.
                Include tokens to insert text based on search results.
                <a href="{{SPLUNKWEB_URL_PREFIX}}/help?location=learnmore.alert.action.tokens" target="_blank"
                   title="Splunk help">Learn More <i class="icon-external"></i></a>
    <div class="control-group">
        <label class="control-label">Message Format</label>

        <div class="controls">
            <label class="radio" for="hipchat_message_format_plain">
                <input id="hipchat_message_format_plain" type="radio" name="action.hipchat.param.message_format" value="plain" />
                Plain Text
            <label class="radio" for="hipchat_message_format_html">
                <input id="hipchat_message_format_html" type="radio" name="action.hipchat.param.message_format" value="html" />
    <div class="control-group">
        <label class="control-label" for="hipchat_color">Background Color</label>

        <div class="controls">
            <select id="hipchat_color" name="action.hipchat.param.color">
                <option value="">None</option>
                <option value="red">Red</option>
                <option value="green">Green</option>
                <option value="blue">Blue</option>
                <option value="grey">Grey</option>
            <span class="help-block">Change the background of the hipchat message.</span>
    <div class="control-group">
        <div class="controls">
            <label class="checkbox" for="hipchat_notify">
                <input type="checkbox" name="action.hipchat.param.notify" id="hipchat_notify" value="1"/>
                Notify users in the room
    <div class="control-group">
        <label class="control-label" for="hipchat_auth_token">Auth Token</label>

        <div class="controls">
            <input type="text" name="action.hipchat.param.auth_token" id="hipchat_auth_token" placeholder="Optional"/>
            <span class="help-block">Override the globally configured HipChat Auth Token for this alert.</span>
Last modified on 13 August, 2019
Logger example for custom alert actions
Advanced options for working with custom alert actions

This documentation applies to the following versions of Splunk® Enterprise: 6.5.7, 7.0.1, 7.0.2, 7.0.3, 7.0.4, 7.0.5, 7.0.6, 7.0.7, 7.0.8, 7.0.9, 7.0.10, 7.0.11, 7.0.13, 7.1.0, 7.1.1, 7.1.2, 7.1.3, 7.1.4, 7.1.5, 7.1.6, 7.1.8, 7.1.9, 7.1.10, 7.2.0, 7.2.1, 7.2.2, 7.2.3, 7.2.4, 7.2.5, 7.2.6, 7.2.7, 7.2.8, 7.2.9, 7.2.10, 7.3.0, 7.3.1, 7.3.2, 7.3.3, 7.3.4, 7.3.5, 7.3.6, 7.3.8, 7.1.7, 7.0.0, 7.3.7, 8.0.2, 8.0.3, 8.0.4, 8.0.5, 8.0.6, 8.0.7, 8.0.8, 8.0.9, 8.0.10, 8.1.0, 8.1.1, 8.1.2, 8.1.3, 8.1.4, 8.1.5, 8.1.6, 8.1.7, 8.1.8, 8.1.9, 8.1.10, 8.1.11, 8.1.12, 8.2.0, 8.2.1, 8.2.2, 8.2.3, 8.2.4, 8.2.5, 8.2.6, 8.2.7, 8.2.8, 8.2.9, 9.0.0, 9.0.1, 9.0.2, 9.0.3, 7.3.9, 8.0.0, 8.0.1

Was this documentation topic helpful?

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters