Oh Dear is the all-in-one monitoring tool for your entire website. We monitor uptime, SSL certificates, broken links, scheduled tasks and more. You'll get a notifications for us when something's wrong. All that paired with a developer friendly API and kick-ass documentation. O, and you'll also be able to create a public status page under a minute. Start monitoring using our free trial now.

How to handle GitHub webhooks in a Laravel application

Original – by Freek Van der Herten – 3 minute read

Whenever something happens in one of your repos on GitHub, you can configure a webhook to be sent to your app. This way, you can perform some extra logic when a particular event occurs on the repo. A silly example would be to send someone a mail when an issue is opened.

We've created a new package called spatie/laravel-github-webhooks that makes it easy to consume GitHub webhooks in a Laravel app. In this blog post, I'd like to tell you all about it.

Are you a visual learner?

In this stream, I show how to use the package, go over the source code, and explain how it is tested.

Using spatie/laravel-github-webhooks

After you've installed the package in your app, you can start configuring what should happen when GitHub webhooks hit your app. GitHub expects your app to respond as fast as possible. That's why the package will, when a webhook comes in, create a GitHubWebhookCall model with the payload of the webhook in the database. It will pass that model to a queued job so that an HTTP response can be sent very quickly, and the actual work that needs to be done can be performed on the queue.

In the jobs key of the github-webhooks config file, you can configure which jobs should be executed when certain events come in. Here's an example:

// in the `github-webhooks` config file

'jobs' => [
    'issues.opened' => \App\Jobs\HandleIssueOpenedWebhookJob::class,

In this example, the HandleIssueOpenedWebhookJob job will be dispatched when a webhook of type issues comes in with an action of opened in the payload.

Here's how the HandeIssueOpenedWebhookJob could look like:

namespace App\Jobs\GitHubWebhooks;

use Illuminate\Bus\Queueable;
use Illuminate\Queue\SerializesModels;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Contracts\Queue\ShouldQueue;
use Spatie\GitHubWebhooks\Models\GitHubWebhookCall;

class HandleIssueOpenedWebhookJob implements ShouldQueue
    use InteractsWithQueue, Queueable, SerializesModels;

    public GitHubWebhookCall $gitHubWebhookCall;

    public function __construct(
        public GitHubWebhookCall $webhookCall
    ) {}

    public function handle()
        // React to the issue opened at GitHub event here

        // You can access the payload of the GitHub webhook call with `$this->webhookCall->payload()`

And that is all you have to do to handle an incoming GitHub webhook in your app.

In closing

spatie/laravel-github-webhooks is very much a meat-and-potatoes kind of package. No new big ideas are introduced here. Still, the package handles a lot of work for you:

  • storing the incoming webhook
  • easy configuration of webhook handling jobs
  • pruning handle webhooks
  • sane exception management

To know more about the package, head over to the readme on GitHub. There are a lot of options not mentioned in this post. Also, be sure to look at this list of packages our team has created previously.

If you want to support our open source efforts, consider picking up one of our paid products.

Stay up to date with all things Laravel, PHP, and JavaScript.

Follow me on Twitter. I regularly tweet out programming tips, and what I myself have learned in ongoing projects.

Every month I send out a newsletter containing lots of interesting stuff for the modern PHP developer.

Expect quick tips & tricks, interesting tutorials, opinions and packages. Because I work with Laravel every day there is an emphasis on that framework.

Rest assured that I will only use your email address to send you the newsletter and will not use it for any other purposes.


What are your thoughts on "How to handle GitHub webhooks in a Laravel application"?

Comments powered by Laravel Comments
Want to join the conversation? Log in or create an account to post a comment.


Bee business liked on 27th July 2021
Fabrizio liked on 27th July 2021
Sanjeeva liked on 27th July 2021
Peter Fox liked on 27th July 2021
Yann Haefliger liked on 27th July 2021
Luke Downing liked on 27th July 2021
Per Steinhorst liked on 27th July 2021
Laravel tweets 🤖 retweeted on 27th July 2021