tjvb/gitlab-webhooks-receiver-for-laravel

Receive webhooks from GitLab and store the data in the database.

v2.3.0 2024-03-12 21:49 UTC

Requires

• php: ~8.1.0 || ~8.2.0 || ~8.3.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
• infection/infection: ^0.26.10 || ^0.27.0
• orchestra/testbench: ^7.0 || ^8.0 || ^9.0
• phpmd/phpmd: ^2.13
• phpstan/phpstan: ^1.4
• phpunit/phpunit: ^9.5 || ^10.0
• squizlabs/php_codesniffer: ^3.5
• thecodingmachine/phpstan-safe-rule: ^1.2

MIT

• Tobias van Beek

• laravel
• gitlab
• webhook
• tjvb

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

1. You can install the package via composer:

   composer require tjvb/gitlab-webhooks-receiver-for-laravel
   

2. You can publish and run the migrations with:

php artisan vendor:publish --provider="TJVB\GitLabWebhooks\GitLabWebhooksServiceProvider" --tag="migrations"
php artisan migrate

1. Listen to the \TJVB\GitLabWebhooks\Events\HookStored::class event. 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.

2. Set the GITLAB_WEBHOOK_SECRET env 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.

3. Create a webhook in GitLab. You can create a webhook in GitLab for your project, group or system. The default url is <application.tld>/gitlabwebhook this can be changed in the configuration from tjvb/gitlab-webhooks-receiver-for-laravel.

4. 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 very welcome to contribute, read about it in CONTRIBUTING

Security

If you discover any security related issues, please email [e-mail] 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 very big. This can be done on the end of your event listener or with a package like spatie/laravel-model-cleanup.

Credits

• Tobias van Beek
• All Contributors

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.