webhook-proxy-go

README

Chathooks - A chat webhook proxy

Chathooks is a webhook proxy service that converts generic outbound webhook messages to a canonical CommonChat message format which is then sent to the chat / team messaging platform of your choice.

This is useful because:

• many services with outbound webhooks need to be formatted before they can be consumed by an inbound webhook. This proxy service does the conversion so you don't have to.
• the conversion can be done one time for all chat / team messaging solutions supported by CommonChat.
• one service can proxy an arbitrary number of webhook sources and event types so you don't have to configure multiple inbound webhooks going to the same group / channel.

It is easy to add additional inbound webhook handlers and outbound webhook adapters by using the adapters.Adapter and handlers.Handler interfaces.

Chathooks currently supports four HTTP server engines.

• Locally - net/http
• Locally - valyala/fasthttp
• AWS Lambda + AWS API Gateway - aws/aws-lambda-go
• AWS Lambda + AWS API Gateway - eawsy/aws-lambda-go-shim (deprecated)

Conversion of the following webhook message formats to Glip inbound webhooks include:

Outbound Webhook Formats supported:

1. Aha!
2. AppSignal
3. Apteligent/Crittercism
4. Circle CI
5. Codeship
6. Confluence
7. Datadog
8. Desk.com
9. Enchant
10. GoSquared
11. Heroku
12. Librato
13. Magnum CI
14. Marketo
15. OpsGenie
16. Papertrail
17. Pingdom
18. Raygun
19. Runscope
20. Semaphore CI, Deploy
21. StatusPage
22. Travis CI
23. Userlike
24. VictorOps

Inbound Webhook Format supported:

• Slack (inbound message format) - text only

Note: Slack inbound message formatting is for services sending outbound webhooks using Slack's inbound webhook message format, which can be directed to Glip via this proxy.

Example Webhook Message from Travis CI:

Installation

$ go get github.com/grokify/chathooks

Configuration

Environment Variables

Chathooks uses two environment variables:

Variable Name	Value
CHATHOOKS_ENGINE	The engine to be used: aws for aws/aws-lambda-go, nethttp for net/http and fasthttp for valyala/fasthttp
CHATHOOKS_TOKENS	Comma-delimited list of verification tokens. No extra leading or trailing spaces.

Engines

Chathooks supports 4 server engines:

• net/http
• valyala/fasthttp
• aws/aws-lambda-go
• eawsy/aws-lambda-go (deprecated)

For aws/aws-lambda-go, net/http, valyala/fasthttp, you can select the engine by setting the CHATHOOKS_ENGINE environment variable to one of: ["aws", "nethttp", "fasthttp"].

Using the AWS Engine

To use the AWS Lambda engine, you need an AWS account. If you don't hae one, the free trial account includes 1 million free Lambda requests per month forever and 1 million free API Gateway requests per month for the first year.

Update Lambda Code:

You can update the Lambda funciton code using the following:

https://docs.aws.amazon.com/cli/latest/reference/lambda/update-function-code.html

$ aws lambda update-function-code --function-name='MyFunction' --zip-file='fileb://main.zip' --publish --region='us-east-1'

Make sure to set your AWS credentials file.

Usage

Starting the Service using FastHTTP

Start the service in main.go.

For testing purposes, use:

$ go run main.go

For production services, compile the code:

$ go build main.go
$ ./main

• To adjust supported handlers, edit server.go to add and remove handlers.

Start the service with the following.

Note: The emoji to URL is designed to take a icon_emoji value and convert it to a URL. EmojiURLFormat is a fmt format string with one %s verb to represent the emoji string without :. You can use any emoji image service. The example shows the emoji set from github.com/wpeterson/emoji forked and hosted at grokify.github.io/emoji/.

Creating the Glip Webhook

1. create a Glip webhook
2. use webhook URL's GUID to create the proxy URL as shown below
3. use the proxy URL in your outbound webhook service

Query Parameter	Required?	URL
inputType	required	An handler service like marketo
outputType	required	An adapter service like glip
url	required	A webhook URL or UID, e.g. 11112222-3333-4444-5555-666677778888
token	optional	Must be included if service is configured to use auth tokens

The webhook proxy URLs support both inbound and outbound formats. When available, these should be represented in the handler key.

To create the Glip webhook and receive a webhook URL do the following:

Add the Webhook Integration

At the top of any conversation page, click the Settings gear icon and then click Add Integration.

Select the Glip Webhooks integration.

Get the Webhook URL

Once you get the URL, the proxy URL is created by appending the GUID (e.g. 1112222-3333-4444-5555-666677778888) to the proxy URL base, hooks?inputType=slack&outputType=glip (e.g. https://glip-proxy.example.com/hooks?inputType=slack&outputType=glip&url=1112222-3333-4444-5555-666677778888). Use the proxy URL in the app that is posting the Slack webhook and the payload will be sent to Glip.

Example Requests

Most of the time you will likely either:

• use the proxy URL in an outbound webhook service that supports the Slack format or
• use a client library

The following examples are provided for reference and testing.

Using application/json

$ curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"username":"ghost-bot", "icon_emoji": ":ghost:", "text":"BOO!"}' \
  "http://localhost:8080/hooks?inputType=slack&outputType=glip&url=11112222-3333-4444-5555-666677778888"

Using application/x-www-form-urlencoded

$ curl -X POST \
  --data-urlencode 'payload={"username":"ghost-bot", "icon_emoji": ":ghost:", text":"BOO!"}' \
  "http://localhost:8080/hooks?inputType=slack&outputType=glip&url=11112222-3333-4444-5555-666677778888"

Using multipart/form-data

$ curl -X POST \
  -F 'payload={"username":"ghost-bot", "icon_emoji": ":ghost:", text":"BOO!"}' \
  "http://localhost:8080?hooks?inputType=slack&outputType=glip&url=11112222-3333-4444-5555-666677778888"

Using Community Ruby SDK

This has been tested using:

• https://github.com/rikas/slack-poster

require 'slack/poster'

url = 'http://localhost:8080?inputType=slack&outputType=glip&url=11112222-3333-4444-5555-666677778888'

opts = {
	username: 'Ghost Bot [Bot]',
	icon_emoji: ':ghost:'
}

poster = Slack::Poster.new url, opts
poster.send_message 'BOO!'

Installation via AWS Lambda

See the AWS docs for deployment:

https://docs.aws.amazon.com/lambda/latest/dg/lambda-go-how-to-create-deployment-package.html

Item	Description
region
lambda-handler
account-id
execution_role
path-to-your-zip-file
lambda-handler

GOOS=linux go build lambda_handler.go
zip handler.zip ./lambda_handler
# --handler is the path to the executable inside the .zip
aws lambda create-function \
  --region region \
  --function-name lambda-handler \
  --memory 128 \
  --role arn:aws:iam::account-id:role/execution_role \
  --runtime go1.x \
  --zip-file fileb://path-to-your-zip-file/handler.zip \
  --handler lambda-handler

Notes

Chathooks is built using:

• net/http

• valyala/fasthttp

• aws/aws-lambda-go

• eawsy/aws-lambda-go-shim

• buaazp/fasthttprouter

• sirupsen/logrus