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.