{"id":15296272,"url":"https://github.com/katmore/webhook","last_synced_at":"2025-10-18T06:11:57.433Z","repository":{"id":57004770,"uuid":"70642729","full_name":"katmore/webhook","owner":"katmore","description":"GitHub Webhook client wrappers and webservice","archived":false,"fork":false,"pushed_at":"2019-04-26T12:44:47.000Z","size":2251,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-30T05:26:36.690Z","etag":null,"topics":["git","github","github-webhooks","microservice","php-library","php7","rest-api","restful-api","webservice"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/katmore.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-10-11T23:08:18.000Z","updated_at":"2022-02-12T12:46:23.000Z","dependencies_parsed_at":"2022-08-21T13:50:59.783Z","dependency_job_id":null,"html_url":"https://github.com/katmore/webhook","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/katmore%2Fwebhook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/katmore%2Fwebhook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/katmore%2Fwebhook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/katmore%2Fwebhook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/katmore","download_url":"https://codeload.github.com/katmore/webhook/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245407755,"owners_count":20610232,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["git","github","github-webhooks","microservice","php-library","php7","rest-api","restful-api","webservice"],"created_at":"2024-09-30T18:09:56.300Z","updated_at":"2025-10-18T06:11:57.346Z","avatar_url":"https://github.com/katmore.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Webhook\n[Github Webhook](https://developer.github.com/webhooks/) client receiver wrappers and webservice.\n\n[Webhook Project Homepage](https://github.com/katmore/webhook)\n\n## Description\nThe 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.\n\n## Requirements\n * PHP 7.2 or higher\n\n## Usage\n### End-point Installer Script\nThe 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. \n\nThe simplest way to prepare the end-point installer is to copy this project somewhere and run Composer:\n```sh\ngit clone https://github.com/katmore/webhook.git \ncd webhook\ncomposer update\n```\nThe 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.):\n\n```sh\nphp bin/add-endpoint.php\n```\nThe `--help` switch will provide details on more advanced usage (such as quiet and non-interactive modes).\n```sh\nphp bin/add-endpoint.php --help\n```\n\n### Wrapper Classes\nTo 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:\n  ```sh\ncomposer require katmore/webhook\n  ```\n\nThe **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). \n\nThe **Payload** object as populated by the **Webhook\\Request** constructor is available using the **Webhook\\Request::getPayload()** method as detailed in the example below:\n\n```php\n/*\n * the 'Secret' field corresponding to the expected Webhook request\n */\n$hubSecret = \"My Secret\";\n\n/*\n * obtain the messageBody; in this case, by reading from the php input stream\n */\n$messageBody = file_get_contents('php://input');\n\n/*\n * obtain the 'hubSignature'; for example, from the value of the HTTP header 'HTTP_X_HUB_SIGNATURE'\n */\n$hubSignature = $_SERVER['HTTP_X_HUB_SIGNATURE'];\n\n/*\n * obtain the 'gitHubEvent'; for example, from the value of the HTTP header 'HTTP_X_GITHUB_EVENT'\n */\n$gitHubEvent = $_SERVER['HTTP_X_GITHUB_EVENT'];\n\n/*\n * instiantate a Webhook\\Request object...\n */\n$request = new \\Webhook\\Request($messageBody, $hubSignature, $gitHubEvent);\n\n/*\n * validate the request signature\n */\n$request-\u003evalidateSignature($hubSecret);\n\n/*\n * get the payload object...\n * For more info on payloads for the various github events, see:\n *    https://developer.github.com/v3/activity/events/types\n */\n$payload = $request-\u003egetPayload();\n\n/*\n * The payload object will be an instance of the \n *    \\Webhook\\Payload\\PushEvent class\n *    if the github event was a 'Push Event'.\n *  \n * The payload object will be an instance of the \n *    \\Webhook\\Payload\\PingEvent class\n *    if the github event was a 'Ping Event'.\n *\n * The payload object will be an instance of the \n *    \\Webhook\\Payload\\Event class\n *    for all other events.\n */\nvar_dump($payload);\n```\n### Validating a request's \"Hub Signature\"\nAt 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). \n\n```php\n/*\n * the 'Secret' field corresponding to the expected Webhook request\n */\n$hubSecret = \"My Secret\";\n\n/*\n * obtain the messageBody, hubSignature, and gitHubEvent\n */\n$messageBody = file_get_contents('php://input');\n$hubSignature = $_SERVER['HTTP_X_HUB_SIGNATURE'];\n$gitHubEvent = $_SERVER['HTTP_X_GITHUB_EVENT'];\n\n/*\n * instiantate a 'Request' object...\n */\n$request = new \\Webhook\\Request($messageBody, $hubSignature, $gitHubEvent);\n\ntry {\n  /*\n   * validate the request signature\n   */\n  $request-\u003evalidateSignature($hubSecret);\n} catch(\\Webhook\\InvalidRequest $e) {\n   /*\n    * force a 500 HTTP response code upon encountering an 'InvalidRequest' exception,\n    */\n   http_response_code(500);\n   echo \"Invalid Request: \".$e-\u003egetMessage();\n   return;\n}\n\n/*\n * continue to do more things...\n */\n//$payload = $request-\u003egetPayload();\n```\n\n### Using the provided end-point example\n\nAn 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.\n\n   * copy the provided [web/endpoint-example.php](web/endpoint-example.php)...\n   \n   ```sh\n   cp web/endpoint-example.php web/my-repo-endpoint.php\n   ```\n   * edit to specify configuration...\n     * change the value of `$config['RepoUrl']` to your GitHub repository URL:\n     \n     ```php\n     $config['RepoUrl'] = 'https://github.com/my-organization/my-repo';\n     ```\n     * change the value of `$config['Secret']` to the \"Secret\" configured in Github for the webhook:\n     \n     ```php\n     $config['Secret'] = 'My Secret';\n     ```\n     * 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:\n     \n     ```php\n     $config['RepoPath'] = '';\n     //$config['RepoPath'] = '/path/to/my/repo';\n     ```\n     \n     * place any custom code within the `onPushEvent` function that should be executed on every 'push' Webhook event\n     \n     ```php\n     function onPushEvent(Payload\\PushEvent $payload) {\n         /*\n          *\n          * --- place code in this function --\n          * --- that should execute when a Github 'push' event occurs --\n          *\n          */\n          //\n          // place your custom code here\n          //\n     }\n     ```\n    \n## Unit Tests\n * [`coverage.txt`](./coverage.txt): unit test coverage report\n * [`phpunit.xml`](./phpunit.xml): PHPUnit configuration file\n * [`tests/phpunit`](./tests/phpunit): source code for unit tests\n\nTo perform unit tests, execute phpunit located in the `vendor/bin` directory.\n```sh\nvendor/bin/phpunit\n```\n\nThe [`tests.sh`](./tests.sh) wrapper script is provided for convenience.\n```sh\n./tests.sh\n```\n\n## Legal\n\"Webhook\" is distributed under the terms of the [MIT license](LICENSE) or the [GPLv3](GPLv3) license.\n\nCopyright (c) 2016-2018, Doug Bird.\nAll rights reserved.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkatmore%2Fwebhook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkatmore%2Fwebhook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkatmore%2Fwebhook/lists"}