Download the PHP package wayofdev/laravel-stripe-webhooks without Composer
On this page you can find all versions of the php package wayofdev/laravel-stripe-webhooks. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download wayofdev/laravel-stripe-webhooks
More information about wayofdev/laravel-stripe-webhooks
Files in wayofdev/laravel-stripe-webhooks
Package laravel-stripe-webhooks
Short Description Handle Stripe webhooks in a Laravel application with support of Cycle-ORM.
License MIT
Homepage https://wayof.dev
Informations about the package laravel-stripe-webhooks
Handle Stripe Webhooks in a Laravel application with Cycle-ORM integration
Stripe can notify your application of various events using webhooks. This package simplifies the process of handling those webhooks. Out of the box, it verifies the Stripe signature for all incoming requests.
Once verified, all valid webhook calls will be logged to the database using Cycle-ORM. You can effortlessly define jobs or events to be dispatched when certain events are received by your app.
However, please note that this package only manages the initial webhook request validation and the dispatching of corresponding jobs or events.
The subsequent actions (e.g., regarding payments) should be implemented separately by the developer. Before diving into this package, it's highly recommended to familiarize yourself with Stripe's comprehensive documentation on webhooks.
If you like/use this package, please consider starring it. Thanks!
πΏ Installation
β Using Composer
Require as dependency:
The service provider will automatically register itself.
β Configuring the Package
You must publish the config file with:
This is the contents of the config file that will be published at config/stripe-webhooks.php
:
In the signing_secret
key of the config file you should add a valid webhook secret. You can find the secret used at the webhook configuration settings on the Stripe dashboard.
β Preparing the Database
By default, all webhook calls will get saved in the database.
To create the table for storing webhook calls:
-
Ensure you've already set up and are running the wayofdev/laravel-cycle-orm-adapter package in your Laravel project.
-
Modify the
cycle.php
config to include theWebhookCall
entity in search paths: -
After updating the config, run the command to generate migrations for the new entity:
(Optional): To see a list of pending migrations:
- Execute any outstanding migrations:
β Configuring Webhook Routing
On the Stripe dashboard, specify the URL at which Stripe should send webhook requests. In your application's route file, map this URL using Route::stripeWebhooks
:
Internally, this command registers a POST
route to a controller provided by this package. As Stripe can't retrieve a csrf-token, exclude this route from the VerifyCsrfToken
middleware:
π» Usage
Stripe dispatches webhooks for various event types. View the complete list of event types in Stripe's official documentation.
Stripe will sign all requests hitting the webhook url of your app. This package will automatically verify if the signature is valid. If it is not, the request was probably not sent by Stripe.
Unless something goes terribly wrong, this package will always respond with a 200
to webhook requests. Sending a 200
will prevent Stripe from resending the same event over and over again. Stripe might occasionally send a duplicate webhook request more than once. This package makes sure that each request will only be processed once. All webhook requests with a valid signature will be logged in the webhook_calls
table. The table has a payload
column where the entire payload of the incoming webhook is saved.
If the signature is invalid, the package will not log the request but will throw a WayOfDev\StripeWebhooks\Exceptions\WebhookFailed
exception. Any errors that occur during a webhook call will be recorded in the exception
column. If there's an error, a 500
response will be sent, otherwise a 200
response.
You can handle webhook requests in two ways with this package: by queuing a job or by listening to the package's events.
β Handling Webhook Requests with Jobs
To take action when a specific event type is received, define a job. Here's a job example:
To ensure prompt responses to webhook requests, consider making the job queueable. This allows for efficient handling of multiple Stripe webhook requests, reducing the chance of timeouts.
After creating the job, register it in the jobs
array of the stripe-webhooks.php
config file. The key should be the name of the stripe event type where but with the .
replaced by _
. The value should be the fully qualified classname.
In case you want to configure one job as default to process all undefined event, you may set the job at default_job
in the stripe-webhooks.php
config file. The value should be the fully qualified classname.
By default, the configuration is an empty string ''
, which will only store the event in database but without handling.
β Handling Webhook Requests with Events
Instead of queueing jobs to perform some work when a webhook request comes in, you can opt to listen to the events this package will fire. Whenever a valid request hits your app, the package will fire a stripe-webhooks::<name-of-the-event>
event.
The payload of the events will be the instance of WebhookCall
that was created for the incoming request.
Let's take a look at how you can listen for such an event. In the EventServiceProvider
you can register listeners.
Here's an example of such a listener:
We highly recommend that you make the event listener queueable, as this will minimize the response time of the webhook requests. This allows you to handle more Stripe webhook requests and avoid timeouts.
To learn about other ways to handle events in Laravel, check out Laravel's official documentation on event handling.
βοΈ Advanced Usage
β Retry Handling a Webhook
All incoming webhook requests are written to the database. This is incredibly valuable when something goes wrong while handling a webhook call. You can easily retry processing the webhook call, after you've investigated and fixed the cause of failure, like this:
β Performing Custom Logic
You can add some custom logic that should be executed before and/or after the scheduling of the queued job by using your own entity. You can do this by specifying your own entity in the entity
key of the stripe-webhooks
config file. The class should extend WayOfDev\StripeWebhooks\Bridge\Laravel\Jobs\ProcessStripeWebhookJob
.
Here's an example:
β Determine if a Request Should be Processed
You may use your own logic to determine if a request should be processed or not. You can do this by specifying your own profile in the profile
key of the stripe-webhooks
config file. The class should implement WayOfDev\WebhookClient\Contracts\WebhookProfile
.
In this example we will make sure to only process a request if it wasn't processed before.
β Handling Multiple Signing Secrets
When using Stripe Connect you might want to the package to handle multiple endpoints and secrets. Here's how to configurate that behaviour.
If you are using the Route::stripeWebhooks
macro, you can append the configKey
as follows:
Alternatively, if you are manually defining the route, you can add configKey
like so:
If this route parameter is present the verify middleware will look for the secret using a different config key, by appending the given the parameter value to the default config key. E.g. If Stripe posts to webhook-url/my-named-secret
you'd add a new config named signing_secret_my-named-secret
.
Example config for Connect might look like:
β Transforming the Webhook Payload into a Stripe Object
You can transform the Webhook payload into a Stripe object to assist in accessing its various methods and properties.
To do this, use the Stripe\Event::constructFrom($payload)
method with the WebhookCall
's payload:
For example, if you have setup a Stripe webhook for the invoice.created
event, you can transform the payload into a StripeInvoice
object:
β‘οΈSequence Diagram
π§ͺ 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-stripe-webhooks 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
All versions of laravel-stripe-webhooks with dependencies
cycle/database Version ^2.8
cycle/orm Version ^2.7
laravel/framework Version ^v10.46
stripe/stripe-php Version ^14.0
wayofdev/laravel-webhook-client Version ^1.3