hookshot

README

Hookshot

Godoc

Hookshot is a Go http router that de-multiplexes and authorizes GitHub Webhooks.

Usage

r := hookshot.NewRouter()

r.Handle("deployment_status", DeploymentStatusHandler)
r.Handle("deployment", DeploymentHandler)

To automatically verify the X-Hub-Signature:

r.Handle("deployment", hookshot.Authorize(DeploymentHandler, "secret"))

Documentation

Overview

Package hookshot is a router that de-multiplexes and authorizes github webhooks.

Example

package main

import (
	"net/http"

	"github.com/ejholmes/hookshot"
)

func HandlePing(w http.ResponseWriter, r *http.Request) {
	w.WriteHeader(200)
	w.Write([]byte(`Pong`))
}

func main() {
	r := hookshot.NewRouter()
	r.HandleFunc("ping", HandlePing)

	http.ListenAndServe(":8080", r)
}

Index

• Constants
• Variables
• func IsAuthorized(r *http.Request, secret string) (string, bool)
• func Signature(body []byte, secret string) string
• type Router
  • func NewRouter() *Router
  • func (r *Router) Handle(event string, h http.Handler)
  • func (r *Router) HandleFunc(event string, fn func(http.ResponseWriter, *http.Request))
  • func (r *Router) Handler(req *http.Request) http.Handler
  • func (r *Router) ServeHTTP(w http.ResponseWriter, req *http.Request)
  • func (r *Router) ServeHTTPContext(ctx context.Context, w http.ResponseWriter, req *http.Request) error
• type SecretHandler
  • func Authorize(h http.Handler, secret string) *SecretHandler
  • func (h *SecretHandler) ServeHTTP(w http.ResponseWriter, req *http.Request)
  • func (h *SecretHandler) ServeHTTPContext(ctx context.Context, w http.ResponseWriter, req *http.Request) error

Examples

• Package
• IsAuthorized

Constants

const (
	// HeaderEvent is the name of the header that contains the type of event.
	HeaderEvent = "X-GitHub-Event"

	// HeaderSignature is the name of the header that contains the signature.
	HeaderSignature = "X-Hub-Signature"
)

Variables

var (
	// DefaultNotFoundHandler is the default NotFoundHandler for a Router instance.
	DefaultNotFoundHandler = http.HandlerFunc(http.NotFound)

	// DefaultUnauthorizedHandler is the default UnauthorizedHandler for a Router
	// instance, which responds with a 403 status and a plain text body.
	DefaultUnauthorizedHandler = http.HandlerFunc(unauthorized)
)

Functions

func IsAuthorized

func IsAuthorized(r *http.Request, secret string) (string, bool)

IsAuthorized checks that the calculated signature for the request matches the provided signature in the request headers. Returns the calculated signature, and a boolean value indicating whether or not the calculated signature matches the X-Hub-Signature value.

Example

h := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	if _, ok := IsAuthorized(r, "secret"); !ok {
		http.Error(w, "The provided signature in the "+HeaderSignature+" header does not match.", 403)
		return
	}

	w.Write([]byte(`Ok`))
})

res := httptest.NewRecorder()
req, _ := http.NewRequest("POST", "", bytes.NewBufferString(`{"data":"foo"}`))
req.Header.Set("X-Hub-Signature", "sha1=b3dc4e9a2d727ee1e60bb6828c2dcef88b5ec970")

h.ServeHTTP(res, req)

fmt.Print(res.Body)

Output:

Ok

func Signature

func Signature(body []byte, secret string) string

Signature calculates the SHA1 HMAC signature of body, signed by the secret.

When github-services makes a POST request, it includes a SHA1 HMAC signature of the request body, signed with the secret provided in the webhook configuration. See http://goo.gl/Oe4WwR.

Types

type Router

type Router struct {
	// NotFoundHandler is called when a handler is not found for a given GitHub event.
	// The nil value for NotFoundHandler
	NotFoundHandler http.Handler
	// contains filtered or unexported fields
}

Router demultiplexes github hooks.

func NewRouter

func NewRouter() *Router

NewRouter returns a new Router.

func (*Router) Handle

func (r *Router) Handle(event string, h http.Handler)

Handle maps a github event to an http.Handler.

func (*Router) HandleFunc

func (r *Router) HandleFunc(event string, fn func(http.ResponseWriter, *http.Request))

HandleFunc maps a github event to an http.HandlerFunc.

func (*Router) Handler

func (r *Router) Handler(req *http.Request) http.Handler

Handler returns the http.Handler to use for the given request. It will always return a non nill Handler.

func (*Router) ServeHTTP

func (r *Router) ServeHTTP(w http.ResponseWriter, req *http.Request)

ServeHTTP implements the http.Handler interface to route a request to an appropriate http.Handler, based on the value of the X-GitHub-Event header.

func (*Router) ServeHTTPContext

func (r *Router) ServeHTTPContext(ctx context.Context, w http.ResponseWriter, req *http.Request) error

ServeHTTPContext implements the httpx.Handler interface.

type SecretHandler

type SecretHandler struct {
	// The secret to use to verify the request.
	Secret string

	// SetHeader controls what happens when the X-Hub-Signature header value does
	// not match the calculated signature. Setting this value to true will set
	// the X-Calculated-Signature header in the response.
	//
	// It's recommended that you only enable this for debugging purposes.
	SetHeader bool

	// Handler is the http.Handler that will be called if the request is
	// authorized.
	Handler http.Handler

	// Unauthorized is the http.Handler that will be called if the request
	// is not authorized.
	Unauthorized http.Handler
}

SecretHandler is an http.Handler that will verify the authenticity of the request.

func Authorize

func Authorize(h http.Handler, secret string) *SecretHandler

Authorize wraps an http.Handler to verify the authenticity of the request using the provided secret.

func (*SecretHandler) ServeHTTP

func (h *SecretHandler) ServeHTTP(w http.ResponseWriter, req *http.Request)

ServeHTTP implements the http.Handler interface.

func (*SecretHandler) ServeHTTPContext

func (h *SecretHandler) ServeHTTPContext(ctx context.Context, w http.ResponseWriter, req *http.Request) error