README

A wrapper for spatie/laravel-webhook-server that provides a simple & flexible webhook registry, allows you to expose any Laravel Event as a webhook, and provides out-of-the-box logging of webhook results.

Installation

Install via composer

composer require custom-d/webhook-registry

Publish Configuration File

php artisan vendor:publish --provider="CustomD\WebhookRegistry\ServiceProvider" --tag="config"

Usage

1. Trigger registered webhooks via events

Implement the CustomD\WebhookRegistry\Contracts\ShouldDeliverWebhooks contract on any Laravel Event, and you'll be able to register webhooks that will be fired on this event.

This contract defines several methods that need to be defined on your event, which will help provide the payload details.

Your payload must define a body, but can also define tags and meta information for passing to Spatie\WebhookServer\WebhookCall.

    /**
     * Get the payload for this webhook event
     */
    public function getWebhookPayload(): array
    {
        return [
            'body' => [
                'status' => $this->status,
            ]
        ];
    }

2. Register webooks

Create webhook endpoints direction using the CustomD\WebhookRegistry\Models\WebhookEndpoint model, or use the facade WebhookRegistry::registerEndpoint.

$endpoint = WebhookRegistry::registerEndpoint(
  'https://webhook.site/custom/endpoint',
  'My webhook endpoint name'
);

By default, we'll verify SSL certificates on outgoing webhook connections. If you want to disable SSL verification, you can pass false to the registerEndpoint function.

$endpoint = WebhookRegistry::registerEndpoint(
  'https://localhost/webhook-test',
  'My insecure endpoint',
  false
);

3. Bind events to an endpoint

Associate a webhook event to an endpoint with the CustomD\WebhookRegistry\Model\WebhookEvent model, or using the facade WebhookRegistry::registerEvent.

$event = WebhookRegistry::registerEvent($webhook->id, 'App\Events\MyEvent');

Models

Customise the WebhookEvent model in order to add logic about when events should fire. In config/webhook-registry.php you will see the models being used in models -> events. You can make your own models by implementing the appropriate contract, and updating the config file.

WebhookEndpoint extends Model implements CustomD\WebhookRegistry\Models\Contracts\WebhookEndpointContract
WebhookEvent extends Model implements CustomD\WebhookRegistry\Models\Contracts\WebhookEventContract

If you need to modify the WebhookRequest logging table, note that it doesn't need a contract and can be overridden as needed, but ensure the original fields exist, or define appropriate attribute mappings.

Custom 'dispatchable' logic

To determine which events are dispatchable in a given execution, you must set a scopeWhereDispatchable on the WebhookEvent model. This scope will be used when finding events that should be fired.

By default this scope doesn't do any filtering.

Security

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

Credits

All contributors

This package is bootstrapped with the help of melihovv/laravel-package-generator.

custom-d / webhook-registry

Maintainers

Details