PHPackages katmore/webhook - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. katmore/webhook ActiveLibrary[API Development](/categories/api) katmore/webhook =============== Wrappers and webservice to handle GitHub Webhook requests. v1.0.9(7y ago)220[1 issues](https://github.com/katmore/webhook/issues)MITPHPPHP >=7.2.1 Since Dec 8Pushed 7y ago1 watchersCompare [ Source](https://github.com/katmore/webhook)[ Packagist](https://packagist.org/packages/katmore/webhook)[ Docs](https://github.com/katmore/webhook)[ RSS](/packages/katmore-webhook/feed)WikiDiscussions master Synced 2mo ago READMEChangelog (10)Dependencies (3)Versions (12)Used By (0) Webhook ======= [](#webhook) [Github Webhook](https://developer.github.com/webhooks/) client receiver wrappers and webservice. [Webhook Project Homepage](https://github.com/katmore/webhook) Description ----------- [](#description) The Webhook Project facilitates workflow integration of Github Webhook requests. It provides [class wrappers](#wrapper-classes) for existing projects and an optional [end-point installer script](#end-point-installer-script) for a self-contained solution that is easy to deploy. Requirements ------------ [](#requirements) - PHP 7.2 or higher Usage ----- [](#usage) ### End-point Installer Script [](#end-point-installer-script) The command-line script [bin/add-endpoint.php](bin/add-endpoint.php) creates a webservice end-point that responds to a Github Webhook for the **PushEvent** on a remote repository by updating a local repository and to a **PingEvent** by displaying a success message. The simplest way to prepare the end-point installer is to copy this project somewhere and run Composer: ``` git clone https://github.com/katmore/webhook.git cd webhook composer update ``` The installer can be invoked without any arguments; it will prompt for all the required parameters (such as the remote URL, local repo path, webhook secret, etc.): ``` php bin/add-endpoint.php ``` The `--help` switch will provide details on more advanced usage (such as quiet and non-interactive modes). ``` php bin/add-endpoint.php --help ``` ### Wrapper Classes [](#wrapper-classes) To use this project's wrapper classes within your existing project, the main topics of focus will be the [**Webhook\\Request** class](src/Request.php) and **Payload** objects. As a recomended first step, add a dependancy using Composer to your existing project: ``` composer require katmore/webhook ``` The **Webhook\\Request** class facilitates interpreting the message body and related HTTP headers of a Github Webhook request. The **Webhook\\Request** class constructor will instantiate and populate a [**Webhook\\Payload**](src/Payload.php) child class having a class name that corresponds to the Webhook "Event Type": it searches for the existence of a class having the same ["short name"](http://php.net/manual/en/reflectionclass.getshortname.php) as the [GitHub Event Type](https://developer.github.com/v3/activity/events/types) within the namespace [**Webhook\\Payload**](src/Payload). If a thusly named **Webhook\\Payload** child class is not defined for a particular event; the [Webhook\\Payload\\Event](src/Payload/Event.php) class is used by default. For example, a [Webhook\\Payload\\PushEvent object](src/Payload/PushEvent.php) is created and populated for a [**PushEvent** Webhook request](https://developer.github.com/v3/activity/events/types/#pushevent). The **Payload** object as populated by the **Webhook\\Request** constructor is available using the **Webhook\\Request::getPayload()** method as detailed in the example below: ``` /* * the 'Secret' field corresponding to the expected Webhook request */ $hubSecret = "My Secret"; /* * obtain the messageBody; in this case, by reading from the php input stream */ $messageBody = file_get_contents('php://input'); /* * obtain the 'hubSignature'; for example, from the value of the HTTP header 'HTTP_X_HUB_SIGNATURE' */ $hubSignature = $_SERVER['HTTP_X_HUB_SIGNATURE']; /* * obtain the 'gitHubEvent'; for example, from the value of the HTTP header 'HTTP_X_GITHUB_EVENT' */ $gitHubEvent = $_SERVER['HTTP_X_GITHUB_EVENT']; /* * instiantate a Webhook\Request object... */ $request = new \Webhook\Request($messageBody, $hubSignature, $gitHubEvent); /* * validate the request signature */ $request->validateSignature($hubSecret); /* * get the payload object... * For more info on payloads for the various github events, see: * https://developer.github.com/v3/activity/events/types */ $payload = $request->getPayload(); /* * The payload object will be an instance of the * \Webhook\Payload\PushEvent class * if the github event was a 'Push Event'. * * The payload object will be an instance of the * \Webhook\Payload\PingEvent class * if the github event was a 'Ping Event'. * * The payload object will be an instance of the * \Webhook\Payload\Event class * for all other events. */ var_dump($payload); ``` ### Validating a request's "Hub Signature" [](#validating-a-requests-hub-signature) At some point in the handling of a Webhook request it is critical that the "Hub Signature" be validated against the shared "Secret" for obvious security reasons. The [end-point installer](#endpoint-installer-script) and [end-point example](#endpoint-installer-script) both accomplish this by using the `Request::validateSignature()` method of the [**Webhook\\Request** class](src/Callback.php). ``` /* * the 'Secret' field corresponding to the expected Webhook request */ $hubSecret = "My Secret"; /* * obtain the messageBody, hubSignature, and gitHubEvent */ $messageBody = file_get_contents('php://input'); $hubSignature = $_SERVER['HTTP_X_HUB_SIGNATURE']; $gitHubEvent = $_SERVER['HTTP_X_GITHUB_EVENT']; /* * instiantate a 'Request' object... */ $request = new \Webhook\Request($messageBody, $hubSignature, $gitHubEvent); try { /* * validate the request signature */ $request->validateSignature($hubSecret); } catch(\Webhook\InvalidRequest $e) { /* * force a 500 HTTP response code upon encountering an 'InvalidRequest' exception, */ http_response_code(500); echo "Invalid Request: ".$e->getMessage(); return; } /* * continue to do more things... */ //$payload = $request->getPayload(); ``` ### Using the provided end-point example [](#using-the-provided-end-point-example) An end-point example is provided at [web/endpoint-example.php](web/endpoint-example.php) which responds to a **PushEvent** by invoking a 'git pull' or any custom code placed in a callback function, as configured. It also responds to a a **PingEvent** with a success message. - copy the provided [web/endpoint-example.php](web/endpoint-example.php)... ``` cp web/endpoint-example.php web/my-repo-endpoint.php ``` - edit to specify configuration... - change the value of `$config['RepoUrl']` to your GitHub repository URL: ``` $config['RepoUrl'] = 'https://github.com/my-organization/my-repo'; ``` - change the value of `$config['Secret']` to the "Secret" configured in Github for the webhook: ``` $config['Secret'] = 'My Secret'; ``` - leave the value of `$config['RepoPath']` empty to skip the repo update, or change it to the local system path of a repository to perform a `git update` on every 'push' Webhook event: ``` $config['RepoPath'] = ''; //$config['RepoPath'] = '/path/to/my/repo'; ``` - place any custom code within the `onPushEvent` function that should be executed on every 'push' Webhook event ``` function onPushEvent(Payload\PushEvent $payload) { /* * * --- place code in this function -- * --- that should execute when a Github 'push' event occurs -- * */ // // place your custom code here // } ``` Unit Tests ---------- [](#unit-tests) - [`coverage.txt`](./coverage.txt): unit test coverage report - [`phpunit.xml`](./phpunit.xml): PHPUnit configuration file - [`tests/phpunit`](./tests/phpunit): source code for unit tests To perform unit tests, execute phpunit located in the `vendor/bin` directory. ``` vendor/bin/phpunit ``` The [`tests.sh`](./tests.sh) wrapper script is provided for convenience. ``` ./tests.sh ``` Legal ----- [](#legal) "Webhook" is distributed under the terms of the [MIT license](LICENSE) or the [GPLv3](GPLv3) license. Copyright (c) 2016-2018, Doug Bird. All rights reserved. ### Health Score 26 — LowBetter than 43% of packages Maintenance10 Infrequent updates — may be unmaintained Popularity9 Limited adoption so far Community7 Small or concentrated contributor base Maturity65 Established project with proven stability Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~96 days Recently: every ~37 days Total 10 Last Release 2575d ago PHP version history (2 changes)v1.0.0PHP >=7.0.1 v1.0.4PHP >=7.2.1 ### Community Maintainers ![](https://www.gravatar.com/avatar/ef3cde32b1ac961c229cb3e76202b38b5d1a2c571334152c6cee08c43732ce7c?d=identicon)[acksponies](/maintainers/acksponies) --- Top Contributors [![ackspony](https://avatars.githubusercontent.com/u/1947018?v=4)](https://github.com/ackspony "ackspony (91 commits)") --- Tags gitgithubgithub-webhooksmicroservicephp-libraryphp7rest-apirestful-apiwebservice ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/katmore-webhook/health.svg) ``` [![Health](https://phpackages.com/badges/katmore-webhook/health.svg)](https://phpackages.com/packages/katmore-webhook) ``` ### Alternatives [stripe/stripe-php Stripe PHP Library 4.0k143.3M480](/packages/stripe-stripe-php)[twilio/sdk A PHP wrapper for Twilio's API 1.6k92.9M272](/packages/twilio-sdk)[knplabs/github-api GitHub API v3 client 2.2k15.8M187](/packages/knplabs-github-api)[facebook/php-business-sdk PHP SDK for Facebook Business 90121.9M34](/packages/facebook-php-business-sdk)[meilisearch/meilisearch-php PHP wrapper for the Meilisearch API 73813.7M114](/packages/meilisearch-meilisearch-php)[google/gax Google API Core for PHP 263103.1M454](/packages/google-gax) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)