loilo / github-webhook-handler
Validate and utilize GitHub webhooks
Requires
- php: ^7.2
- ext-hash: *
- ext-json: *
- psr/http-message: ^1.0
Requires (Dev)
- guzzlehttp/psr7: ^1.4
- mockery/mockery: ^1.3
- phpunit/phpunit: ^7.0
This package is auto-updated.
Last update: 2024-10-24 07:20:12 UTC
README
GitHub Webhook Handler
Handle GitHub webhooks with PHP.
Installation
composer require loilo/github-webhook-handler
Usage
Start by creating a handler:
$handler = new Loilo\GithubWebhook\Handler($secret);
$secret
is the webhook secret defined in the GitHub backend. It can be omitted, however providing it is strongly recommended to prevent abuse of the endpoint.
To handle a request (specifically, a PSR-7 ServerRequestInterface
), pass that request to the handle
method:
$delivery = $handler->handle($request);
If the webhook request is invalid, a failure-specific exception will be thrown. Otherwise, the method returns a Delivery
object which provides access to the event that caused the hook request and to the payload data that was sent along with it:
// Get the triggered event (e.g. 'push') $delivery->event(); // Get the whole webhook payload as an associative array $delivery->payload(); // Get a nested path in the payload (returns `null` if the path doesn't exist) $delivery->payload('repository.full_name');
Single-File Endpoint
There may be very simple cases where you're not using a PHP framework for your script and just want to put a single PHP file endpoint out there. To avoid having to deal with exceptions and creating appropriate error responses, you may use the respond()
method:
$delivery = $handler->respond($request);
Now you can safely use the $delivery
object without any further worries — if validation of the webhook request fails, the handler will set an appropriate HTTP status code, print the error message and stop script execution.
Pro Tip: Not having a PSR-7 request object at hand? Install the
guzzlehttp/psr7
package and use\GuzzleHttp\Psr7\ServerRequest::fromGlobals()
to create a request object from the environment.