# Webhook helpers (optional)

If you're creating a new Laravel application and need to handle Paddle's webhooks, Kanuu's Laravel package provides a HandlePaddleWebhook controller that can help you get started in no time.

Diagram showing your application between Kanuu and Paddle.

# 1. Add your Paddle's public key

First, the package will need your Paddle's public key so it can verify the signature of Paddle's webhooks. On your Paddle's account, go to "Developer Tools > Public Key" and copy your public key.

Paddle screenshot of the "Public Key" page.

Then, paste it in your .env file. It should like this.

-----END PUBLIC KEY-----"

# 2. Register the webhook route

Similarly to the redirectRoute() helper method, Kanuu provides a webhookRoute() helper method to define in your routes/web file.


You can now tell Paddle about your new webhook URL so it can start notifying you of new events. Whilst you're there, make sure the 3 subscription webhook events are selected.

Paddle's screenshot of the "Alerts and Webhooks" page.

Finally, since webhooks cannot be CSRF protected, you'll need to disable that route on the VerifyCsrfToken middleware.

protected $except = [

# 3. Add subscription listeners

We're now listening to Paddle's webhook but not doing anything about it. Let's make sure we add our custom logic to these subscription events.

Go to your AppServiceProvider (or any other service provider), and add the following webhook listeners.

Kanuu::on('subscription_created', function ($payload, $identifier) {
    // Create a new subscription in your application...

Kanuu::on('subscription_updated', function ($payload, $identifier) {
    // Update an existing subscription in your application...

Kanuu::on('subscription_cancelled', function ($payload, $identifier) {
    // Mark an existing subscription as cancelled in your application...

If you want to combine the logic of multiple events in one listener, you can use wildcard events like this:

Kanuu::on('subscription_*', function ($payload, $identifier) {
    // Listens to any event starting with "subscription_".
    // Here we would update or create a subscription based on the payload.

Finally, you're likely going to reuse the same logic across all your listeners to parse the $identifier into a model that make sense to your application. You can parse that $identifier into a model before reaching a listener by calling the getModelUsing helper method.

// Parse the identifier into a model once.
Kanuu::getModelUsing(function ($identifier) {
    return User::findOrFail($identifier);

// It is now already parsed in all your listeners.
Kanuu::on('subscription_*', function ($payload, User $user) {
    // ...

At this point, we've facilitate handling Paddle's webhooks but we still have to create some sort of Subscription model attached to our billable entity and implement the logic of our listeners.

Since this logic greatly depends on how your application handles billing, you might want to come up with your own models and migrations here. However, Kanuu's Laravel package can help you get started by publishing some boilerplate into your application.

In the next page, we'll see how we can use this package to generate the Subscription boilerplate we need to have billing all set up.