Receiver - A Drop-in Webhook Handling Library for Laravel

Receiver is a drop-in webhook handling library for Laravel.

Webhooks are a powerful part of any API lifecycle. Receiver aims to make handling incoming webhooks in your Laravel app a consistent and accessible process.

Out of the box, Receiver has built-in support for:

• GitHub Webhooks
• Hubspot Webhooks
• Postmark Webhooks
• Slack Events API
• Stripe Webhooks

Installation

You can install this package via composer.

composer require hotmeteor/receiver

Receiving Webhooks

The Basics

Webhooks require an exposed endpoint to POST to. Receiver aims to make this a one-time setup that supports any of your incoming webhooks.

• Create a controller and route for the webhooks you expect to receive.
• Receive the webhook and handle it, as necessary:

<?php

namespace App\Http\Controllers\Webhooks;

use App\Http\Controllers\Controller;
use Illuminate\Http\Request;

class WebhooksController extends Controller
{
   public function store(Request $request)
   {
       Receiver::driver('slack')
           ->receive($request)
           ->ok();
   }
}

• The methods being used are simple:
• Define the driver that should process the webhook
• receive the request for handling
• Respond back to the sender with a 200 ok response

Handling Webhooks

The Basics

Now that webhooks are being received they need to be handled. Receiver will look for designated Handler classes for each event type that comes into the App\Http\Handlers[Driver] namespace. Receiver does not provide these handlers – they are up to you to provide as needed. If Receiver doesn’t find a matching handler it simply ignores the event and responds with a 200 status code.

For example, a Stripe webhook handler would be App\Http\Handlers\Stripe\CustomerCreated for the incoming customer.created event.

Each handler is constructed with the event (name of the webhook event) and data properties.

<?php

namespace App\Http\Handlers\Stripe;

class CustomerCreated
{
    public function __construct(public string $event, public array $data)
    {
    }

    public function handle()
    {
        // Your code here
    }
}

Securing Webhooks

Many webhooks have ways of verifying their authenticity as they are received, most commonly through signatures or basic authentication. No matter the strategy, Receiver allows you to write custom verification codes as necessary. Simply implement the verify method in your provider and return true or false if it passes.

A false return will result in a 401 response being returned to the webhook sender.

<?php

namespace App\Http\Controllers\Webhooks;

use App\Http\Controllers\Controller;
use Illuminate\Http\Request;

class WebhooksController extends Controller
{
    public function verify(Request $request): bool
    {
        // return result of verification
    }

    public function store(Request $request, string $driver)
    {
        Receiver::driver($driver)
            ->receive($request)
            ->ok();
    }
}

Above are the basic details about this package, If you want to learn more, please visit Github