Webhooks User Guide

In this user guide, you will see how to configure Tehama to send Activity Stream events generated by your organization to a third-party service.

The page where this configuration is set up and maintained is under the WEBHOOKS tab found on your organization's ORGANIZATION settings page in the Tehama Web UI.

Currently, Tehama provides integration with the following:

Splunk (See Splunk's own documentation here: https://www.splunk.com)
Any server that supports the Syslog protocol (See a description of Syslog here: https://en.wikipedia.org/wiki/Syslog)

Splunk

Tehama provides integration with the third-party service Splunk. You can use Splunk to aggregate all kinds of different machine data from the various third-party and in-house tools that your company uses, including events from Tehama.

Tehama provides a guide to integrating with Splunk. See "Webhooks Splunk Setup".

Enable sending events to Splunk

Integration with Splunk from Tehama has been tested with Splunk version 7.1.3.

Follow Splunk's own documentation at http://docs.splunk.com/Documentation/Splunk/7.1.3 to create an activity stream for Tehama in Splunk's HTTP Event Collector.

Take note of:

the URL for the endpoint of your Splunk instance's HTTP Event Collector. (1)
the token value for the activity stream you created for Tehama in the HTTP Event Collector. (2)
the name of the default index provided in the above activity stream. (3)

Then:

Log in to the Tehama Web UI as the Org Admin user for your organization.
Click on the ORGANIZATION tab in the navigation bar.
Click on the WEBHOOKS tab.
Click on the SPLUNK tab in the page.
Enter the endpoint URL, (1) above, into the field URL of your Splunk instance's HTTP Collector endpoint.
Enter the token value, (2) above, into the field Splunk Token (Authorization header value).
Enter the default index name, (3) above, into the field Index to send events to.
Select the transmission type in the Data transmission method field.
- Select Direct if you want Tehama to transmit events directly to Splunk through a public internet connection. (Splunk provides a secure transmission mechanism.) This transmission type is useful when you have a publicly available Splunk instance.
- Select Room Connection if you want Tehama to transmit events through the internet connection of one of your organization's rooms. This transmission type is useful when you have a Splunk instance that resides within in your organization's private network. The selected room should be connected either through a Multi-Path connection or through a Tehama Gateway to your private network and thus be able to access your Splunk instance without you needing to open your private network's firewall.
If you selected the Room Connection transmission option, then select the room you wish Tehama to use - be sure to configure that room's firewall rules to allow access to your Splunk instance's HTTP Event Collector, (1) above. (If your Room is a Multi-Path Room, and its DNS Filtering feature is active, be sure to add any domains for the HTTP Event Collector to the list of allowed domains.)
Click SEND TEST EVENT. A message will appear indicating if the test was successful or if an error occurred. If there was an error, the message will indicate the type of error. (Note that if you selected 'Room Connection' as your transmission option under the 'Data transmission method' field, then, in a Tehama Gateway Room, the gateway for the room you selected must be running. If the test still fails, you may be directed to the 'Connection Test' page for the room to diagnose the issue.)

The SEND TEST EVENT button will be disabled after each successful test until the configuration is changed.
Once a successful test has completed, it is recommended that you manually verify that the test event appeared in the Splunk instance. After you have verified this, you can click SAVE CONFIGURATION. From the instant you click on SAVE CONFIGURATION Tehama will send all Activity Stream events it generates for your organization to the Splunk instance whose configuration you just saved, until you delete it or supersede it with a new configuration.
Alternately, you can click RESET to revert your Splunk configuration to the last saved configuration (if there is one).

Delete Splunk configuration

To delete the Splunk configuration:

Log in to the Tehama Web UI as the Org Admin user for your organization.
Click on the ORGANIZATION tab in the navigation bar.
Click on the WEBHOOKS tab.
Click on the SPLUNK tab in the page.
Click on the DELETE button. You will see a confirmation dialog.

Note that the DELETE button will be disabled while you are entering or testing a new configuration. If you want to delete the last saved configuration, click RESET to return to the last saved configuration and to enable the DELETE button.
Confirm that you want to delete the configuration.

NOTE: It may be possible to disable, temporarily or permanently, the activity stream you created for Tehama in your Splunk instance's HTTP Event Collector. See Splunk's user documentation for information about disabling this feature from Splunk.

Syslog

Tehama provides integration with any third-party event-logging service that supports the Syslog protocol. You can use a Syslog protocol supporting service to aggregate all kinds of different machine data from the various third-party and in-house tools that your company uses, including events from Tehama.

Syslog is not a secure protocol. Tehama secures transmission of the syslog-formatted events it sends by transmitting all events through the internet connection of one of your organization's rooms. The room's firewall rules must be configured to allow access to your chosen service. (If the room is a Multi-Path Room, and its DNS Filtering feature is active, be sure to add any domains for your chosen service to the list of allowed domains.) If your service is located within the private network connected to the room, the events should remain secure, and you will not need to make your service publicly available.

See documentation for your chosen third-party event-logging service for information on how to set it up to receive Tehama events that are sent using the syslog protocol.

Enable sending events in the Syslog Protocol

Integration with a syslog supporting service from Tehama has been tested with the RFC 5424 Syslog standard (see https://tools.ietf.org/html/rfc5424).

Integration has also been tested with the informal BSD Syslog (RFC 3164) (see https://tools.ietf.org/html/rfc3164)

Take note of:

the URL for the endpoint for your Syslog supporting third-party event-logging service.

Then:

Log in to the Tehama Web UI as the Org Admin user for your organization.
Click on the ORGANIZATION tab in the navigation bar.
Click on the WEBHOOKS tab.
Click on the SYSLOG tab in the page.
Select the protocol you want with the Protocol toggle - either tcp or udp.
Enter the endpoint URL for your service into the field IP or Host Name.
Enter the Port for your service - the default is 514.
Enter the Facility Code for the events - the default is 1 (user-level messages).
Enter the Severity Code for the events - the default is 6 (informational messages).

(See RFC 5424 section 6.2.1 or RFC 3164 section 4.1.1 for more information on facility codes and severity codes.)
Select the Syslog standard you wish to use - the default is RFC 3164. Toggle the switch to "off" to use the standard RFC 5424.
Select the room whose internet connection you want Tehama to transmit the events through in the dropdown field under Room Connection - be sure to configure that room's firewall rules to allow access to the endpoint URL for your service (the value in the IP or Host Name field above). (If the room is a Multi-Path Room, and its DNS Filtering feature is active, be sure to add any domains for your chosen service to the list of allowed domains.)
Click SEND TEST EVENT. A message will appear indicating if the test was successful or if an error occurred. If there was an error, the message will indicate the type of error. (Note that, in a Tehama Gateway Room, the gateway for the room you selected for the room-connection under the 'Data transmission method' field must be running. If the test still fails, you may be directed to the 'Connection Test' page for the room to diagnose the issue.)

The SEND TEST EVENT button will be disabled after each successful test until the configuration is changed.
Once a successful test has completed, it is recommended that you manually verify that the test event appeared in the service. After you have verified this, you can click SAVE CONFIGURATION. From the instant you click on SAVE CONFIGURATION Tehama will send all Activity Stream events it generates for your organization to the service whose configuration you just saved, until you delete it or supersede it with a new configuration.
Alternately, you can click RESET to revert your Syslog service configuration to the last saved configuration (if there is one).

Delete Syslog configuration

To delete the Syslog configuration:

Log in to the Tehama Web UI as the Org Admin user for your organization.
Click on the ORGANIZATION tab in the navigation bar.
Click on the WEBHOOKS tab.
Click on the SYSLOG tab in the page.
Click on the DELETE button. You will see a confirmation dialog.

Note that the DELETE button will be disabled while you are entering or testing a new configuration. If you want to delete the last saved configuration, click RESET to return to the last saved configuration and to enable the DELETE button.
Confirm that you want to delete the configuration.

NOTE: It may be possible to disable, temporarily or permanently, the activity stream you created for Tehama in your service. See your service's user documentation for information.

Event Types

In order to make the most of the events your third-party service (e.g.: Splunk) will be receiving from Tehama, you will need to know what events to expect and what data they contain.

Each event sends a list of arguments along with it. These consist of a set of default arguments that every event type contains and the list of arguments specific to each event type.

Tehama provides this information in a special report, called "Webhooks Event Types".

Both the SPLUNK and SYSLOG tabs within the WEBHOOKS page contain a short-cut to display this report.

From either the SPLUNK or SYSLOG tabs, click on Webhooks Event Types Report to view the report.

You will be directed to the REPORTS page with the Webhooks Event Types report-type selected, as in the image below:

Tehama Reports Webhooks Event Types

This report contains the event name, a description of the event, the category the event belongs to and a list of the arguments specific to that event along with their types which can be atomic types, like String or Boolean or custom argument schemas like Room Schema or User Schema.

Click on the argument schema name (like Room Schema) in an entry to see the list of arguments in that schema.

Click on the Click to view default arguments sent with every event (user and organization and type) link above the report list to see the list of default arguments sent with every event (the Event Schema).

You can download this report as a 'Comma Separated List' (CSV) or in 'Portable Document Format' (PDF).

(See more information on how to view/filter/download reports in the Reports User Guide.)