NAME
Plack::App::GitHub::WebHook - GitHub WebHook receiver as Plack application
VERSION
version 0.3
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}}) {
...
}
}
)->to_app;
# 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'
]
)->to_app;
# this is equivalent to
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 (for instance because it did not origin from GitHub).
- 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, if the hook was called and returned a true value.
- HTTP 202 Accepted
-
Otherwise, if the hook was called and returned a false value.
This module requires at least Perl 5.10.
CONFIGURATION
- hook
-
A code reference that gets passed the encoded payload. Alternatively derive a subclass from Plack::App::GitHub::WebHook and implement the method
receive
instead. The hook or receive method is expected to return a true value. If it returns a false value, the application will return HTTP status code 202 instead of 200. One can use this mechanism for instance to detect hooks that were called successfully but failed to execute for some reason. - 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.
SEE ALSO
WWW::GitHub::PostReceiveHook uses Web::Simple to receive GitHub web hooks. Net::GitHub and Pithub provide access to GitHub APIs.
AUTHOR
Jakob Voß
COPYRIGHT AND LICENSE
This software is copyright (c) 2014 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.