Webhook

This is a webhook app meant to handle webhook calls from the various items across the crops organization.

POST Headers

Each POST is expected to have the following headers.

X-Github-Event

The event calling the webhook is expected to be in an http header X-GitHub-Event.
X-Hub-Signature

Authorization is handled by an http header identified by X-Hub-Signature. This header is the hmac digest of the payload created using a secret key and sha1. The digest will always be prefixed with sha1=.

For example, the digest could be created using the following call to openssl:
```
echo -n "somedata" | openssl sha1 -hmac secretkey
```
And then sha1= would be prefixed. A full signature may look like:
```
sha1=5a2985bd0a3e4e35691add40bb16943749f576b7
```

Configuration

Default The default configuration consists of the following values:
```
HANDLERS_FILE = '/etc/crops-webhook/handlers.cfg'
KEY_FILE = '/etc/crops-webhook/key'
ROUTE = '/webhook'
WHITELIST_ENV = ''
```
Any of these values can be overridden in a file specified in the CROPS_WEBHOOK_CONFIG environment variable.
- HANDLERS_FILE
  
  This specifies the file containing information on what script to call for each handler. It's format is described in the Event Handlers section.
- KEY_FILE
  
  This file contains the key used to generated the hmac digest for the payload. The key can also be specified using the CROPS_WEBHOOK_KEY environment variable.
- ROUTE
  
  The route is the portion of the url that will come after where your webapp is hosted. For instance if we were hosting on localhost, and the route was set to myroute:
```
http://localhost/myroute
```
- WHITELIST_ENV
  
  This specifies the file containing information on what environment variables are whitelisted for each event. The format is described below.
  
  If WHITELIST_ENV is set to a valid file then the environment inside inside the handler for each event will only contain the environment variables explicitly listed for the event.
  
  In other words, if an event is not listed in the WHITELIST_ENV file, the handler for the event will run with an empty environment.
  
  This is useful for restricting what the handlers can see from the main webhook process. For instance if the webhook process has multiple keys stored in its environment, the WHITELIST_ENV file lets you only show what is necessary to the handler.
  - WHITELIST_ENV format
    
    The WHITELIST_ENV file contains one section called Whitelist. In the section, there should be event/whitelist pairs.
    
    Here is an example WHITELIST_ENV file:
```
[Whitelist]
event=VAR1 VAR2
anotherevent=ANOTHERVAR MOREVAR
```

Event Handlers

HANDLERS_FILE format

When the webhook is called, the app will check HANDLERS_FILE to determine what to call for the event. It is expected the file will have a Handlers section followed by event/handler pairs for each event that should be handled.

The handler can either be an absolute path, or it can be a path that is relative to the HANDLERS_FILE.

This is an example configuration file:
```
[Handlers]
event=/somepath/somescript.sh
anotherevent=relativepath/someotherapp.py
```
For an example, assume that HANDLERS_FILE=/handlers/handlers.cfg. Using the example handlers.cfg above, the directory layout would be:
```
.
├── handlers
│   ├── handlers.cfg
│   └── relativepath
│       └── sometotherapp.py
└── somepath
    └── somescript.sh
```
Handler API
- Inputs
  
  A handler can be any type of executable file. When the handler is executed, it will be passed a directory name. If there was a payload with the event, the payload will be in a file called payload.
  
  In other words, if the handler was called myhandler.sh, it would be like running the following command from the shell.
```
myhandler.sh /somedir
```
  And if there was a payload received, the directory layout would look like:
```
.
└── somedir
    └── payload
```
- Output
  
  If a handler needs to send a response other than the default, the handler can create a file called response for this purpose.
  
  Once again, lets assume the directory passed to the handler was somedir. Then to send a response, before exiting the handler, the handler would create a file called response. That would create a directory layout:
```
.
└── somedir
    └── response
```

Example handler

Here is a very simple handler in shell script. The handler will check for some data in the payload and respond differently based on the payload.

#!/bin/bash

# Get the directory containing the payload
workdir=$1

# Get the payload
payload=$workdir/payload

# Set the location of response
response=$workdir/response

if grep "expected data" $workdir/payload; then
    echo -n "Got expected data" > $workdir/response
else
    echo -n "Didn't get expected data" > $workdir/response
fi

And now the same in python instead:

#!/usr/bin/env python

import sys
import os

# Get the directory containing the payload
workdir = sys.argv[1]

# Get the payload file
payload = os.path.join(workdir, 'payload')

# Set the location of response
response = os.path.join(workdir, 'response')

datafound = False
with open(payload, 'r') as f:
    for line in f:
        if 'expected data' in line:
           datafound=True
           break

with open(response, 'w') as f:
    if datafound:
        f.write("Got expected data")
    else:
        f.write("Didn't get expected data")

crops/webhook

Webhook

POST Headers

Configuration

Event Handlers