NAME
    Net::API::Stripe::WebHook::Apache - An Apache handler for Stripe Web
    Hook

SYNOPSIS
        package My::Module::WebHook;
        BEGIN
        {
            use strict;
            use curry;
            use parent qw( Net::API::Stripe::WebHook::Apache );
        };
    
        sub init
        {
            my $self = shift( @_ );
            $self->{event_handlers} =
            {
            account => { updated => $self->curry::account_updated,
            # etc..
            # See here for a list of Stripe events:
            # https://stripe.com/docs/api/events/types
            };
        }

VERSION
        v0.100.1

DESCRIPTION
    This is the module to handle Stripe Web Hooks using Apache/mod_perl
    configuration

    The way this works is you create your own module which inherits from
    this one. You override the init method in which you create the object
    property *event_handler* with an hash value with keys corresponding to
    the types of Stripe events. A dot in the Stripe event type corresponds
    to a sub hash in our *event_handler* definition.

    When an http query is made by Stripe on your webhook, Apache will
    trigger the method handler, which will check and create the object
    environment, and call the method event_handler provided by this package
    to find out the sub in charge of this Stripe event type, as defined in
    your map *event_handlers*. You own method is then called and you can do
    whatever you want with Stripe data.

    It is also worth mentioning that Stripe requires ssl to be enabled to
    perform webhook queries.

CONFIGURATION
    Your Apache VirtualHost configuration would look something like this,
    assuming your module package is "My::Module::WebHook"

        <VirtualHost *:443>
            ServerName example.com:443
            ServerAdmin www@example.com
            DocumentRoot /home/john/example.com
            DirectoryIndex "index.html" "index.php"
            CustomLog "${APACHE_LOG_DIR}/example.com-access.log" combined
            ErrorLog "${APACHE_LOG_DIR}/example.com-error.log"
            LogLevel warn
            <Directory "/home/john/example.com">
                Options All +MultiViews -ExecCGI -Indexes +Includes +FollowSymLinks
                AllowOverride All
            </Directory>
            ScriptAlias "/cgi-bin/"     "/home/john/example.com/cgi-bin/"
            <Directory "/home/john/example.com/cgi-bin/">
                Options All +Includes +ExecCGI -Indexes -MultiViews
                AllowOverride All
                SetHandler cgi-script
                AcceptPathInfo On
                    Require all granted
            </Directory>
            <IfModule mod_perl.c>
                            PerlOptions             +GlobalRequest
                            PerlPassEnv             MOD_PERL
                            PerlPassEnv             PATH_INFO
                            PerlModule              Apache2::Request
                            <Perl>
                            unshift( @INC, "/home/john/lib" );
                            </Perl>
                            <Location /hook>
                                    SetHandler              perl-script
                                    ## Switch it back to modperl once the soft is stable
                                    # SetHandler            modperl
                                    PerlSendHeader          On
                                    PerlSetupEnv            On
                                    PerlOptions                     +GlobalRequest
                                    # PerlResponseHandler   Net::API::Stripe::WebHook::Apache
                                    PerlResponseHandler My::Module::WebHook
                                    Options                         +ExecCGI
                                    Order allow,deny
                                    Allow from all
                            </Location>
            </IfModule>

            SSLCertificateFile /etc/letsencrypt/live/example.com/cert.pem
            SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
            Include /etc/letsencrypt/options-ssl-apache.conf
            SSLCertificateChainFile /etc/letsencrypt/live/example.com/chain.pem
        </Virtualhost>

    The key part is the line with "PerlResponseHandler" and value
    Net::API::Stripe::WebHook::Apache. This will tell Apache/mod_perl that
    our module will handle all http request for this particular location.

    So, if we get an incoming event from Stripe at
    https://example.com/hook/d18bbab7-e537-4dba-9a1f-dd6cc70ea6c1, we
    receive "d18bbab7-e537-4dba-9a1f-dd6cc70ea6c1" as part of the path info,
    and we call validate_webhook() to validate it before processing the
    event incoming packet.

    Apache will call our special method handler(), which will invoque
    validate_webhook() that should be overriden by your module, and which
    must return either true or false. Upon successful return from
    validate_webhook(), handler will create a new constructor such as
    $class->new()

    What you want to do is inherit Net::API::Stripe::WebHook::Apache and set
    your own module in Apache configuration, like so:

        PerlResponseHandler My::WebHookHandler

    The inherited handler will be called by Apache with the class
    My::WebHookHandler and the apache Apache2::RequestRec object. As we
    wrote above, once validated, handler will initiate an object from your
    module by calling "My::WebHookHandler-"new( object =>
    Net::API::Stripe::Event, request => Net::API::REST::Request, response =>
    Net::API::REST::Response )> where each package name are an object.
    "object" represents the event packet received from Stripe. "request" is
    an object to access great number of method to access the Apache API, and
    "response" is an object to access Apache API to provide a reply. See the
    manual page for each of those package.

CONSTRUCTOR
    new( %args )
        Creates a new Net::API::Stripe::WebHook::Apache object. This should
        be overriden by your own package.

        *object* Net::API::Stripe::Event object
        *request* Net::API::REST::Request
        *request* Net::API::REST::Response

    handler( $class, $r )
        This is called by Apache/mod_perl upon incoming http request

METHODS
    handler( $r )
        This is called by Apache with an Apache2::Request object and returns
        an Apache2::Constant code such as 200

    event_handler( Stripe event type )
        Provided with a Stripe event type, this checks for a suitable
        handler (set up in your init method), then return the handler code
        reference.

        ~item event_handlers

        Set/get an hash reference of Stripe event type to handling methods.

        Returns an hash reference.

    stripe
        Set/get a Net::API::Stripe object. It returns the current value.

HISTORY
  v0.1
    Initial version

AUTHOR
    Jacques Deguest <jack@deguest.jp>

SEE ALSO
    Stripe API documentation: <https://stripe.com/docs/api/events/types>

    Net::API::REST, Apache2

    ModPerl::Registry, ModPerl::PerlRun, <http://perl.apache.org/>

COPYRIGHT & LICENSE
    Copyright (c) 2019-2020 DEGUEST Pte. Ltd.

    You can use, copy, modify and redistribute this package and associated
    files under the same terms as Perl itself.