NAME

Plack::App::GitHub::WebHook - GitHub WebHook receiver as Plack application

VERSION

version 0.2

SYNOPSIS

use Plack::App::GitHub::WebHook;

Plack::App::GitHub::WebHook->new(
    hook => sub {
        my $payload = shift;

        return unless $payload->{repository}->{name} eq 'foo-bar';

        foreach (@{$payload->{commits}}) {
            ...
        }
);


# access restriction, as enabled by default
Plack::App::GitHub::WebHook->new(
    hook => sub { ... },
    access => [
        allow => "204.232.175.64/27",
        allow => "192.30.252.0/22",
        deny  => 'all'
    ]
);


# alternatively
use Plack::Builder;

builder {
    mount 'notify' => builder {
        enable 'Access', rules => [
            allow => "204.232.175.64/27",
            allow => "192.30.252.0/22",
            deny  => 'all'
        ]
        Plack::App::GitHub::WebHook->new(
            hook => sub { ... }
        );
    }
};

DESCRIPTION

This PSGI application receives HTTP POST requests with body parameter payload set to a JSON object. The default use case is to receive GitHub WebHooks.

The response of a HTTP request to this application is one of:

HTTP 403 Forbidden

If access was not granted.

HTTP 405 Method Not Allowed

If the request was no HTTP POST.

HTTP 400 Bad Request

If the payload was no well-formed JSON. A later version of this module may add further validation.

HTTP 200 OK

Otherwise. The hook is only called in this case. The hook should not die; a later version of this module may also catch errors.

This module requires at least Perl 5.10.

CONFIGURATION

hook

A code reference that gets passed the encoded payload.

access

Access restrictions, as passed to Plack::Middleware::Access. See SYNOPSIS for the default value. A recent list of official GitHub WebHook IPs is vailable at https://api.github.com/meta. One should only set the access value on instantiation, or manually call prepare_app after modification.

AUTHOR

Jakob Voß

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Jakob Voß.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.