Hi,
I’m new to Sensu go. I want to use generic webhook integration with applications other than slack. Can someone provide me documentation around setting up a generic webhook for sending alerts to different applications.services other than Slack/MS Teams?
Hey,
so normally i would just write a small script to use as a Sensu pipe handler command. The pipe handler command can be any executable the sensu-backend process is allowed to run on the host system. The Sensu backend provides a json representation of (optionally mutated) sensu event on the executable’s stdin. So any script that can read a json string from stdin can be used as a pipe handler command to communicate with any external service. If its a bash script I’d use a combo of jq and curl inside the script to manipulate the json data and then post it to the http endpoint. If it were python, I’d just use the json and requests modules in the script to manipulate the provided json and then post it to wherever I need.
For basic script development testing outside of Sensu I just use something like
sensuctl event info --format json <entity-name> <check-name> | ./my-custom-handler-script
and then once I know the script is working, I’ll make sure to provision it on the sensu-backend system in a location where the sensu-backend process can run the custom script, and then write the handler definition to use it as the command
It’s absolutely okay to have in-house handler scripts like this if you need them. You control the sensu-backend host provisioning, so you can have whatever you want for executables available. They just don’t make for sharable assets with other users because of the system specific dependencies, so its not something you’ll see me sharing as examples. Golang works great for reusable sharable plugins (statically compiled inside of Sensu assets means no deps to provision), which is why we’ve provided a golang sensu plugin sdk to help write handlers plugins that are easy to package as assets and share.
But, you got me thinking about it, and i put together a generic http post handler written in golang as a proof of concept for a sharable generic http handler.
https://bonsai.sensu.io/assets/jspaleta/sensu-http-handler
This generic http handler should allow you to send the json string passed to the handler on stdin to most webhook urls in a generic fashion. In fact it doesn’t even try to validate that the string is valid json… it just passes it along as the body of the http POST request in the most generic way possible.
There’s a caveat though, doing things generically like this means no longer having the ability to use advanced features like field templating that makes use of Sensu event data structure to fill in specific fields the webhook expects. The reason why the dedicated slack handler can use template strings that reference the check or entity, or make use of check/entity annotation overrides for the channel to use is because it ingests a valid Sensu event, and knows details about the slack api’s expected payload structure. None of that is available to a generic http handler because a generic handler can’t assume its being handed a valid Sensu event on stdin and knows nothing about the targer service’s expected payload.
Whatever its being handed to this generic http handler is at best valid json, but ideally its whatever the endpoint expects to see as a request payload. Using a generic http handler puts more responsibility on the user to mutate the Sensu event json into the correct json structure expected by the target service. You have to make sure you write the mutator for the specific service to convert the Sensu event json into whatever the destination webhook url expects as a json payload.
Unless you’re extra lucky, and the webhook you want to send data to knows how to consume Sensu event json without modification (this is very rare), you’re now probably going to need to write a Sensu mutator to make changes to the json so the webhook accepts it as valid.
So that’s handlers covered, lets talk about mutators…
Mutators are given a json representation of a Sensu event on stdin but they must also output a json string on stdout, because the output of a mutator is expected to be the input of a handler. And like pipe handlers, mutators can be any executable available on system for sensu-backend to run. So if you need to write a mutator using jq in a bash script… that’ll work in a pinch.