A generic webhook endpoint that runs scripts based on the URL called
Branch: master
Clone or download
Latest commit 44f61b8 Jan 20, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
contrib Added a systemd service to control captainhook May 25, 2014
example working May 20, 2014
.gitignore trying release Jan 20, 2019
.gitpod gitpod Nov 12, 2018
.gometalinter.json trying release Jan 20, 2019
.goreleaser.yml generated goreleaser Jan 20, 2019
.travis.yml trying release Jan 20, 2019
Dockerfile Go Releaser and vgo support Mar 2, 2018
Dockerfile.multi update build for post-vgo Jan 20, 2019
Makefile version bump: 0.1.19 Jan 20, 2019
README.md shoulders Jan 20, 2019
SHOULDERS.md version bump: v0.1.19 Jan 20, 2019
doc.go more docs May 21, 2014
gitpod.Dockerfile gitpod Nov 12, 2018
go.mod update to vgo compatibility Mar 29, 2018
go.modverify update to vgo compatibility Mar 29, 2018
hook.go Support IPv6 network Dec 22, 2018
main.go update to vgo compatibility Mar 29, 2018
runbook_test.go Hooks should define allowed networks Mar 18, 2015
version.go version bump: 0.1.20 Jan 20, 2019



Build Status

A generic webhook endpoint that runs scripts based on the URL called

This tool was built as part of a CI orchestration process, to be called when Docker trusted builds finish. It explicitly ignores the posted data from the webhook because that would be insecure, which is bad.

Shoulders of Giants

Captainhook would not be possible if not for all of the great projects it depends on. Please see SHOULDERS.md to see a list of them.

Quick Start

Install captainhook

go get github.com/bketelsen/captainhook

Create the configdir

mkdir ~/captainhook

Add a script

    "scripts": [
            "command": "ls",
            "args": [
            "command": "echo",
            "args": [

Name this script endpoint1.json

Start the service

captainhook -configdir ~/captainhook

Test using curl

curl -X POST http://localhost:8080/endpoint1

Configure calling webhooks

Each script you create in the configdir will be executed when the corresponding endpoint is called.

If you have a script called deployBigApp.json you would trigger it by posting to http://your.captainhook.url/deployBigApp.

The scripts in the json file are executed sequentially, and the output is logged and returned to the caller in the response, which always has an HTTP status code of 200 (OK) even if your scripts didn't work. This is intentional, to avoid causing errors in external services like Docker or Github, which might not like you returning statuses other than 200 (OK).

Accessing the Request POST Body

You'll sometimes need to access the POST data of the request for information such as a callback URL. You can pass the raw POST data to a script by adding {{POST}} to the script arguments.

    "scripts": [
            "command": "echo",
            "args": [

Limiting access for webhooks

You can limit who can call your webhooks by specifying "allowedNetworks" in the json config.

    "scripts": [
            "command": "echo"
    "allowedNetworks": [

This would allow your hook to be called from the network, or from localhost.

Supporting proxy headers for client IP

Only enable proxy support if you are on a trusted network behind a reverse proxy. End-users with direct network access can subvert the allowedNetworks restriction if proxy support is on.

captainhook -configdir ~/captainhook -enable-proxy -proxy-header X-Forwarded-For


docker pull bketelsen/captainhook
mkdir /some/local/config
$EDITOR /some/local/config/myhook.json
docker run -d -v /some/local/config:/config bketelsen/captainhook


captainhook requires Go 1.10 to build locally with 'vgo' support.

go get github.com/bketelsen/captainhook



mkdir -p $GOPATH/src/github.com/bketelsen
cd $GOPATH/src/github.com/bketelsen
git clone git@github.com:bketelsen/captainhook.git
go build .

To Do

  • more logs

Copyright 2014, Brian Ketelsen and Kelsey Hightower LICENSE information found in LICENSE file.