tjvb / gitlab-webhooks-receiver-for-laravel
Receive webhooks from GitLab and store the data in the database.
Requires
- php: ~8.1.0 || ~8.2.0 || ~8.3.0 || ~8.4.0
- ext-json: *
- laravel/framework: ^9.0 || ^10.0 || ^11.0
- nesbot/carbon: ^2.0
- thecodingmachine/safe: ^2.0
Requires (Dev)
- fakerphp/faker: ^1.14
- friendsofphp/php-cs-fixer: ^3.64
- infection/infection: ^0.26.10 || ^0.27.0
- orchestra/testbench: ^7.0 || ^8.0 || ^9.0
- phpmd/phpmd: ^2.13
- phpstan/extension-installer: ^1.3
- phpstan/phpstan: ^1.11
- phpstan/phpstan-strict-rules: ^1.6
- phpunit/phpunit: ^9.5 || ^10.0
- slevomat/coding-standard: ^8.15
- squizlabs/php_codesniffer: ^3.5
- symplify/easy-coding-standard: ^12.3
- thecodingmachine/phpstan-safe-rule: ^1.2
README
GitLab has the option to send webhooks for multiple events that can be used for different purposes. This package handle the receiving, validating and storing of the webhook data. After receiving it will dispatch an event that can be used to do with the data what fits your application.
Installation
You can install the package via composer:
composer require tjvb/gitlab-webhooks-receiver-for-laravelYou can publish and run the migrations with:
php artisan vendor:publish --provider="TJVB\GitLabWebhooks\GitLabWebhooksServiceProvider" --tag="migrations"
php artisan migrate
Listen to the
\TJVB\GitLabWebhooks\Events\HookStored::classevent. The package store the webhook data and dispatch an event, you can listen to the HookStored event and handle it the way you want. The Laravel documentation can explain more about events and listeners.Set the
GITLAB_WEBHOOK_SECRETenv variable (most used version is to set it in the .env file) to have the token you use for your webhook. See https://docs.gitlab.com/ee/user/project/integrations/webhooks.html#secret-token for more information.Create a webhook in GitLab. You can create a webhook in GitLab for your project, group or system. The default url is
<application.tld>/gitlabwebhookthis can be changed in the configuration from tjvb/gitlab-webhooks-receiver-for-laravel.Optional configure the package.
Manual register the service provider.
If you disable the package discovery you need to add \TJVB\GitLabWebhooks\GitLabWebhooksServiceProvider::class, to the providers array in config/app.php
Configuration
Customization
You can publish the config file with:
php artisan vendor:publish --provider="TJVB\GitLabWebhooks\GitLabWebhooksServiceProvider" --tag="config"
Security
The default configuration validates the X-Gitlab-Token in the header of the webhook request. It is possible to add multiple values in the config file or disabling the middleware to stop the verification. If you need more validation for the request (as example and i.p. filter) you can add more middleware to the configuration.
Changelog
We (try to) document all the changes in CHANGELOG so read it for more information.
Contributing
You are welcome to contribute, read about it in CONTRIBUTING
Security
If you discover any security related issues, please email info@tjvb.nl instead of using the issue tracker.
Tips
Fast response
As described here GitLab want to have a fast response. That means that it is useful to have a queue driver configured that run the jobs in the background. That means that if you use the sync driver it can happen that the response is to slow, so you get the webhook another time.
Test your webhook
On the GitLab pages with the webhook settings it is possible to test the webhook, use it to verify that everything works as suspected.
Cleanup your hooks
If you don't need the data saved in the webhook it can be a good idea to periodic remove the old data. Depending on the kind of hooks the body can be big. This can be done on the end of your event listener or with a package like spatie/laravel-model-cleanup.
Credits
Thanks to
- GitLab for the great product, without that this package isn't needed.
License
The MIT License (MIT). Please see License File for more information.