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

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

This package is auto-updated.

Last update: 2024-06-12 21:28:19 UTC


Latest Stable Version Pipeline status Coverage report Tested on PHP 8.1 to 8.3 Tested on Laravel 9 to 11 Latest Unstable Version

PHP Version Require Laravel Version Require PHPMD PHPStan PHPCS


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.


  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 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



You can publish the config file with:

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


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.


We (try to) document all the changes in CHANGELOG so read it for more information.


You are very welcome to contribute, read about it in CONTRIBUTING


If you discover any security related issues, please email instead of using the issue tracker.


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.


Thanks to

  • GitLab for the great product, without that this package isn't needed.


The MIT License (MIT). Please see License File for more information.