Creating Outbound Notifications for Glip using Webhooks

The most popular integration use cases for the RingCentral Glip team messaging service are to present notifications in other applications within Glip to specific teams and users. This way, Glip can become the central app for you and your team to learn about, respond to and collaborate on events for all your apps. Webhooks are a popular way to send this information to any app, however, the information needs to be formatted for Glip to be human readable.

Glip itself, has many of these integrations built-in, but you may want to add a service that is not supported out-of-the-box or customize your message format, you’ll want to be able to create your own webhook integration which well cover in this article with the following topics:

• Webhooks overview: inbound and outbound webhooks
• Creating a Glip inbound webhook
• Using an outbound webhook service with Glip
• Using a webhook proxy to manage webhook formatting

The first 3 sections provide an overview of webhooks while the last covers an app that can automatically handle the message conversion for you.

The easiest way to create these integrations involves no formatting using either an outside service like Zapier or an outbound webhook service with custom formatting. Beyond that, we’ll cover message formats and the webhookproxy open source webhook proxy framework to do it yourself.

Webhooks Overview

Webhooks are HTTP URLs that are used to post and receive messages to services. To create a webhook integration, you will need both an “inbound webhook” service and an “outbound webhook” service:

• Inbound webhook: an inbound webhook service is one that creates a webhook URL to listen to posts of a specific type.
• Outbound webhook: this is a service where you register your inbound webhook URL for a service to send posts to, typically when an notification event is triggered.

Glip supports both inbound and outbound webhooks. For inbound alert notifications which we will discuss in this article, inbound Glip webhooks are used. Outbound Glip webhooks are suitable for chatbot use cases.

For more information on webhooks, see the Wikipedia webhook page and Webhooks.org.

Creating a Glip Inbound Webhook

Glip’s inbound webhook service available in Glip by creating a “Glip WebHooks” integration. You can create a webhook by clicking the Settings icon in the upper right corner of a Glip conversation in the web or desktop app. After you click “Add Integrations”, search for webhook as shown below:

Once you select this item, a webhook URL will be generated for you to use in your app with formatting instructions for your webhook. The Glip Webhook itself will resemble something like the following:

https://hooks.glip.com/webhook/11112222-3333-4444-5555-666677778888

The Glip webhook format supports a JSON message body with Markdown in the text, such as the following:

{
  "icon": "http://tinyurl.com/pn46fgp",
  "activity": "Beer consumed",
  "title": "Jeff is having a Maple Bacon Coffee Porter",
  "body": "* Location: [The Funky Buddha Lounge](http://www.thefunkybuddha.com)\n*Beer Advocate Rating: [99](http://tinyurl.com/psf4uzq)"
}

Supported Markdown includes *italics* , **bold** , [a link](http://google.com), > quote , ~strikethrough~ , _underline_ , * list items , and |multi|column|tables| .

You can programmatically create webhook messages using any HTTP client or the following community libraries:

• Ruby: ringcentral-ruby/glip-poster-ruby
• Go: grokify/glip-go-webhook

Using an outbound webhook service with Glip

You can create a program to call the webhook URL yourself, however, one of the most popular ways of using Glip inbound webhooks is with a service that has outbound webhooks, like Desk.com, Heroku, Marketo, Travis CI, etc.

There are 2 kinds of outbound webhook services, those that support custom formatting and those that do not described below:

Fixed Format Outbound Webhook

Most outbound webhook services, like Heroku and Travis CI, use fixed outbound messages, typically in JSON format. Because the outbound format is typically not the same as an inbound webhook format for Glip or any other inbound webhook format, a conversion must be done from one format to the other using an intermediate service such as a webhook proxy discussed below.

A typical fixed format outbound webhooks loks like the following. As you can see, it doesn’t look like Glip inbound format so some formatting is needed before the message can be used within Glip.

{
    "comment":{
        "spaceKey":"~admin",
        "parent":{
            "spaceKey":"~admin",
            "modificationDate":1471926079631,
            "creatorKey":"ff80808154510724015451074c160001",
            "creatorName":"admin",
            "lastModifierKey":"ff80808154510724015451074c160001",
            "self":"https://cloud-development-environment.atlassian.net/wiki/display/~admin/Some+random+test+page",
            "lastModifierName":"admin",
            "id":16777227,
            "title":"Some random test page",
            "creationDate":1471926079631,
            "version":1
        },
        "modificationDate":1471926091465,
        "creatorKey":"ff80808154510724015451074c160001",
        "creatorName":"admin",
        "lastModifierKey":"ff80808154510724015451074c160001",
        "self":"https://cloud-development-environment/wiki/display/~admin/Some+random+test+page?focusedCommentId=16777228#comment-16777228",
        "lastModifierName":"admin",
        "id":16777228,
        "creationDate":1471926091465,
        "version":1
    },
    "user":"admin",
    "userKey":"ff80808154510724015451074c160001",
    "timestamp":1471926091468,
    "username":"admin"
}

Custom Format Outbound Webhook

Another type of outbound webhook service is one that supports custom formatting, typically using a built-in templating engine that can be formatted in a UI. Services that have this capability include Datadog, Desk.com, Marketo, Sumo Logic, and VictorOps. The power of this approach is that you can directly customize the outbound webhook format in this app so that it matches the Glip format without needing any intermediate service. While this is a more powerful outbound webhook implementation, relatively few services support this.

An example of a custom format webhook configuration is shown below for Marketo. You can see the template editor where you will enter a Glip formatted message using Marketo variables to be posted directly into Glip.

In both cases, you will create an outbound webhook service in the desired app and add the Glip inbound webhook URL for the app to send notifications to.

Using a Webhook Proxy to Manage Webhook Formatting

To making formatting outbound webhook formats to Glip’s inbound webhook format easier, you can use a webhook proxy which will create a substitute webhook URL for you to call. This service will then do the translation and forward the message to Glip.

Two approaches that will describe include using a 3rd party service, like Zapier, and running your own, like the webhookproxy project.

Using Zapier’s Webhook Service

To use Zapier, sign up for an account and select “Webhooks by Zapier” for the trigger and Glip as the action. When you set up Zapier webhooks, select “Catch Hook” which will load outbound wehbook variables to use for you in creating your Glip message.

Using the webhookproxy Open Source Webhook Proxy Framework

Zapier is a great service when the service’s capabilities support your needs. When you want something more custom, you can create your own webhook handler or use a webhook proxy framework like webhookproxy written in Go on Github:

https://github.com/grokify/webhookproxy/

The webhookproxy project provides a proxy capability that can translate messages from many services out of the box and forward it to your service of choice, currently supporting Glip. To use webhookproxy, you can use one of the 24 handlers and send it to Glip, or create your own.

https://github.com/grokify/webhookproxy/tree/master/src/handlers

The proxy works by taking the Glip Webhook URL GUID and adding it to it’s own inbound webhook URL. When it receives message on that URL, it passes the message to the registered handler for special formatting before the message is delivered to the configured adapter.

In addition to being based on Go, the project uses valyala/fasthttp and buaazp/fasthttprouter .

The router configuration looks like the following. See more in the project’s documentation.

package main
import(
    log "github.com/Sirupsen/logrus"
    "github.com/buaazp/fasthttprouter"
    "github.com/valyala/fasthttp"
    "github.com/grokify/webhookproxy/src/adapters"
    "github.com/grokify/webhookproxy/src/config"
    "github.com/grokify/webhookproxy/src/handlers/travisci"
)
func main() {
    cfg := config.Configuration{
        Port:     8080,
        LogLevel: log.DebugLevel}
    adapter, _ := adapters.NewGlipAdapter("")
    router := fasthttprouter.New()
    handler := travisci.NewHandler(cfg, &adapter)
    router.POST("/hook/travisci/:webhookuid", handler.HandleFastHTTP)
    log.Fatal(fasthttp.ListenAndServe(cfg.Address(), router.Handler))
}

Summary

• Glip is a great way to keep track of all your cloud apps in a single place.
• Webhooks are a great way to notify Glip of events in other services.
• Some services used fixed formatting and others use custom formatting. Custom formatted outbound webhooks can be used with Glip out of the box while fixed formatting integrations may need a converter if they are not already supported by Glip natively.
• There are webhook translation services and open source projects to give you the most flexibility.

If you want to learn more about any of these ways to integration Glip, please post a comment to this article. Also, please tell us how you are using webhooks with Gip!