Download the PHP package wayofdev/laravel-webhook-client without Composer

Receive webhooks in Laravel apps

Webhooks offer a mechanism for one application to inform another about specific events, typically using a straightforward HTTP request.

The wayofdev/laravel-webhook-client package facilitates the reception of webhooks in a Laravel application, leveraging the power of cycle-orm. Features include verifying signed calls, storing payload data, and processing the payloads in a queued job.

This package is inspired by and re-written from the original spatie/laravel-webhook-client to incorporate Cycle-ORM support.

💿 Installation

→ Using composer

Require as dependency:

→ Configuring the package

You can publish the config file with:

This is the contents of the file that will be published at config/webhook-client.php:

In the signing_secret key of the config file, you should add a valid webhook secret. This value should be provided by the app that will send you webhooks.

This package will try to store and respond to the webhook as fast as possible. Processing the payload of the request is done via a queued job. It's recommended to not use the sync driver but a real queue driver. You should specify the job that will handle processing webhook requests in the process_webhook_job of the config file. A valid job is any class that extends WayOfDev\WebhookClient\Bridge\Laravel\Jobs\ProcessWebhookJob and has a handle method.

→ Preparing the database

By default, all webhook calls will get saved in the database.

To create the table that holds the webhook calls:

1. You must have already configured and running wayofdev/laravel-cycle-orm-adapter package in your Laravel project.

2. Edit cycle.php config to add WebhookCall entity to search paths:

3. After editing config, run command to generate new migrations from newly appeared entity:

   (Optional): To view list of migrations, to be executed:

4. Run outstanding migrations using command:

→ Taking care of routing

Finally, let's take care of the routing. At the app that sends webhooks, you probably configure an URL where you want your webhook requests to be sent. In the routes file of your app, you must pass that route to Route::webhooks. Here's an example:

Behind the scenes, by default this will register a POST route to a controller provided by this package. Because the app that sends webhooks to you has no way of getting a csrf-token, you must add that route to the except array of the VerifyCsrfToken middleware:

💻 Usage

Once you've completed the installation, here's a comprehensive breakdown of how the package functions:

1. Signature Verification:
   • The package initiates by verifying the incoming request's signature.
   • If the signature doesn't pass the verification, an exception is thrown, the InvalidSignatureEvent event is fired, and the request isn't saved to the database.
2. Webhook Profile Evaluation:
   • Each incoming request interacts with a webhook profile, which is essentially a class that evaluates if a request should be both saved and processed within your application.
   • This profile enables filtering of specific webhook requests based on the app's requirements.
   • Your own custom webhook profile can be created, to change or extend this logic.
3. Storage & Processing:
   • If the profile gives the go-ahead, the request is first saved in the webhook_calls table.
   • Subsequently, a queued job handles the WebhookCall entity.
   • Webhooks usually expect a fast response, so by queuing jobs, we can respond quickly.
   • Configuration for the job processing the webhook is found under the process_webhook_job in the webhook-client config file.
   • If any issues arise during job queuing, the package logs the exception within the exception field of the WebhookCall entity.
4. Webhook Response:
   • Once the job is dispatched, a webhook response takes charge. This class determines the HTTP response for the request.
   • By default, a 200 status code with an 'ok' message is returned. However, you can also craft a custom webhook response. Learn how to easily create your own webhook response.

→ Verifying the signature of incoming webhooks

This package assumes that an incoming webhook request has a header that can be used to verify the payload has not been tampered with. The name of the header containing the signature can be configured in the signature_header_name key of the config file. By default, the package uses the DefaultSignatureValidator to validate signatures. This is how that class will compute the signature.

If the $computedSignature does match the value, the request will be passed to the webhook profile. If $computedSignature does not match the value in the signature header, the package will respond with a 500 and discard the request.

→ Creating your own signature validator

A signature validator is any class that implements WayOfDev\WebhookClient\Contracts\SignatureValidator. Here's what that interface looks like.

WebhookConfig is a data transfer object that lets you easily pull up the config (containing the header name that contains the signature and the secret) for the webhook request.

After creating your own SignatureValidator you must register it in the signature_validator in the webhook-client config file.

→ Determining which webhook requests should be stored and processed

After the signature of an incoming webhook request is validated, the request will be passed to a webhook profile. A webhook profile is a class that determines if the request should be stored and processed. If the webhook sending app sends out request where your app isn't interested in, you can use this class to filter out such events.

By default, the \WayOfDev\WebhookClient\Profile\ProcessEverythingWebhookProfile class is used. As its name implies, this default class will determine that all incoming requests should be stored and processed.

→ Creating your own webhook profile

A webhook profile is any class that implements \WayOfDev\WebhookClient\Contracts\WebhookProfile. This is what that interface looks like:

After creating your own WebhookProfile you must register it in the webhook_profile key in the webhook-client config file.

→ Storing and processing webhooks

After the signature is validated and the webhook profile has determined that the request should be processed, the package will store and process the request.

The request will first be stored in the webhook_calls table, involving the WebhookCall entity and the WebhookCallRepository.

Should you want to customize the table name or anything on the storage behavior, the package grants flexibility to employ an alternative entity.This can be done by setting the desired entity in the webhook_entity.

Ensure your entity is derived from WayOfDev\WebhookClient\Entities\WebhookCall. For storage purposes, the WebhookCallRepository interface alongside its implementation, ORMWebhookCallRepository, come into play. Modifications to the default repository can be made through webhook_entity_repository.

You can change how the webhook is stored by overriding the store method of ORMWebhookCallRepository In the store method you should return persisted entity.

Next, the newly created WebhookCall entity will be passed to a queued job that will process the request. Any class that extends \WayOfDev\WebhookClient\Bridge\Laravel\Jobs\ProcessWebhookJob is a valid job. Here's an example:

You should specify the class name of your job in the process_webhook_job of the webhook-client config file.

→ Creating your own webhook response

A webhook response is any class that implements \WayOfDev\WebhookClient\Contracts\RespondsToWebhook. This is what that interface looks like:

After creating your own WebhookResponse you must register it in the webhook_response key in the webhook-client config file.

→ Handling incoming webhook request for multiple apps

This package allows webhooks to be received from multiple different apps. Let's take a look at an example config file where we add support for two webhook URLs. All comments from the config have been removed for brevity.

When registering routes for the package, you should pass the name of the config as a second parameter.

→ Change route method

Being an incoming webhook client, there are instances where you might want to establish a route method other than the default post. You have the flexibility to modify the standard post method to options such as get, put, patch, or delete.

→ Using the package without a controller

If you don't want to use the routes and controller provided by your macro, you can programmatically add support for webhooks to your own controller.

WayOfDev\WebhookClient\WebhookProcessor is a class that verifies the signature, calls the web profile, stores the webhook request, and starts a queued job to process the stored webhook request. The controller provided by this package also uses that class under the hood.

It can be used like this:

→ Deleting entities

Whenever a webhook comes in, this package will store as a WebhookCall entity. After a while, you might want to delete old entities.

@todo Laravel version uses mass-prunable trait, so, entity deletion logic should be re-written using laravel console commands or by committing to cycle-orm.

In this example all entities will be deleted when older than 30 days.

🧪 Running Tests

→ PHPUnit tests

To run tests, run the following command:

→ Static Analysis

Code quality using PHPStan:

→ Coding Standards Fixing

Fix code using The PHP Coding Standards Fixer (PHP CS Fixer) to follow our standards:

🤝 License

🧱 Credits and Useful Resources

This repository is based on the spatie/laravel-webhook-client work.

🙆🏼‍♂️ Author Information

Created in 2023 by lotyp / wayofdev

🙌 Want to Contribute?

Thank you for considering contributing to the wayofdev community! We are open to all kinds of contributions. If you want to:

• 🤔 Suggest a feature
• 🐛 Report an issue
• 📖 Improve documentation
• 👨‍💻 Contribute to the code