Handling Webhooks with Laravel

Webhooks are perfect solutions to connect different services. But still, it can be a blind spot for many developers. In this post, we try to present how webhooks work with a real-life example.

Webhooks in General

Basically, a webhook in nothing else, but an endpoint where we can run a callback when it got hit. For example, we have a third-party integration and when it performs some action it hits the webhook’s endpoint then we can react for that.

Mostly all the big services offer the possibility of webhook integrations. Slack, Stripe, and GitLab as well. We will take a look at a GitLab integration and how to handle it on the Laravel end.

Even Laravel Forge uses webhooks for custom deployment. We already wrote an article about integrating it with Codeship.

Setting Up a GitLab Webhook

If you have an existing repository, you can set up different integrations for it. Navigate to the Settings > Integrations tab to handle your repository’s integrations. You can instantly add a new webhook to your repo.

So first, you need to define the URL you want to hit. It has to be a full URL for example https://yourapp.com/webhook.

As a second option, you can set a token. It’s handy when you want to ensure the request is by GitLab. It will be attached to the X-Gitlab-Token header, and for example, in a middleware, you can check if it’s a correct one or not.

Then you can select different events when you want to trigger your request. For now, the Push events will be fine. It means, on every git push the webhook will be called.

Every request will contain info about the repository. You can find them in the docs, and use them for your needs!

Handling the Incoming Webhook

First of all, we have to set the route for the webhook. We used the /webhook URI in the example, so let’s stick with that.

 Route::post('webhook', '[email protected]');
Since GitLab sends a POST request we have to set a POST route for that. But for the different services, it can be GET or another request type as well.

As a second step, we need to disable the CSRF token validation for this route. Since the request comes outside of the session, it does not contain the proper CSRF token. We can add the route to the exceptions where the validation is not required. Open the VerifyCsrfToken middleware and add the route to the $except property.

protected $except = [
    'webhook',
];

After the previous steps, all we have to do to create the WebhookController and add the handle method.

class WebhookController extends Controller
{
    public function handle(Request $request)
    {
        // Perform your action
    }
}

In the handle method (or name it however you want) you can perform the action you want. It can be anything. The point is, you have your custom callback and you can reflect on the events you want to.

Summary

It’s a very basic example of using webhooks, of course, there are much more complex use cases. You may want to verify the webhook call or process the given payload or giving a proper response to the request itself. Many things can go on, but as basics, you now see how webhooks work and how to use them easily with Laravel.