Webhook response customisation (#56)

* Add webhookresponse interface and default class

* Create response inside processor, instead of controller

* Update documentation

* Fix StyleCI issue

* Add 'Response' return type to interface method

Co-authored-by: GuntherDebrauwer <[email protected]>

Author: gdebrauwer

README.md

@@ -6,15 +6,15 @@
 [![Quality Score](https://img.shields.io/scrutinizer/g/spatie/laravel-webhook-client.svg?style=flat-square)](https://scrutinizer-ci.com/g/spatie/laravel-webhook-client)
 [![Total Downloads](https://img.shields.io/packagist/dt/spatie/laravel-webhook-client.svg?style=flat-square)](https://packagist.org/packages/spatie/laravel-webhook-client)
 
-A webhook is a way for an app to provide information to another app about a specific event. The way the two apps communicate is with a simple HTTP request. 
+A webhook is a way for an app to provide information to another app about a specific event. The way the two apps communicate is with a simple HTTP request.
 
 This package allows you to receive webhooks in a Laravel app. It has support for [verifying signed calls](#verifying-the-signature-of-incoming-webhooks), [storing payloads and processing the payloads](#storing-and-processing-webhooks) in a queued job.
 
 If you need to send webhooks, take a look at our [laravel-webhook-server](https://github.com/spatie/laravel-webhook-server) package.
 
 ## Support us
 
-We invest a lot of resources into creating [best in class open source packages](https://spatie.be/open-source). You can support us by [buying one of our paid products](https://spatie.be/open-source/support-us). 
+We invest a lot of resources into creating [best in class open source packages](https://spatie.be/open-source). You can support us by [buying one of our paid products](https://spatie.be/open-source/support-us).
 
 We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on [our contact page](https://spatie.be/about-us). We publish all received postcards on [our virtual postcard wall](https://spatie.be/open-source/postcards).
 
@@ -69,6 +69,11 @@ return [
              */
             'webhook_profile' => \Spatie\WebhookClient\WebhookProfile\ProcessEverythingWebhookProfile::class,
 
+            /*
+             * This class determines the response on a valid webhook call.
+             */
+            'webhook_response' => \Spatie\WebhookClient\WebhookResponse\DefaultResponse::class,
+
             /*
              * The classname of the model to be used to store call. The class should be equal
              * or extend Spatie\WebhookClient\Models\WebhookCall.
@@ -87,7 +92,7 @@ return [
 
 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 `Spatie\WebhookClient\ProcessWebhookJob` and has a `handle` method. 
+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 `Spatie\WebhookClient\ProcessWebhookJob` and has a `handle` method.
 
 ### Preparing the database
 
@@ -122,13 +127,13 @@ protected $except = [
 
 ## Usage
 
-With the installation out of the way, let's take a look at how this package handles webhooks. First, it will verify if the signature of the request is valid. If it is not, we'll throw an exception and fire off the `InvalidSignatureEvent` event. Requests with invalid signatures will not be stored in the database. 
+With the installation out of the way, let's take a look at how this package handles webhooks. First, it will verify if the signature of the request is valid. If it is not, we'll throw an exception and fire off the `InvalidSignatureEvent` event. Requests with invalid signatures will not be stored in the database.
 
 Next, the request will be passed to a webhook profile. A webhook profile is a class that determines if a request should be stored and processed by your app. It allows you to filter out webhook requests that are of interest to your app. You can easily create [your own webhook profile](#determining-which-webhook-requests-should-be-stored-and-processed).
 
 If the webhook profile determines that request should be stored and processed, we'll first store it in the `webhook_calls` table. After that, we'll pass that newly created `WebhookCall` model to a queued job. Most webhook sending apps expect you to respond very quickly. Offloading the real processing work allows for speedy responses. You can specify which job should process the webhook in the `process_webhook_job` in the `webhook-client` config file. Should an exception be thrown while queueing the job, the package will store that exception in the `exception` attribute on the `WebhookCall` model.
 
-After the job has been dispatched, the controller will respond with a `200` status code. 
+After the job has been dispatched, the request will be passed to a webhook response. A webhook response is a class that determines the HTTP response for the request. An 'ok' message response with `200` status code is returned by default, but you can easily create [your own webhook response](#creating-your-own-webhook-response).
 
 ### Verifying the signature of incoming webhooks
 
@@ -142,7 +147,7 @@ If the `$computedSignature` does match the value, the request will be [passed to
 
 ### Creating your own signature validator
 
-A signature validator is any class that implements `Spatie\WebhookClient\SignatureValidator\SignatureValidator`. Here's what that interface looks like. 
+A signature validator is any class that implements `Spatie\WebhookClient\SignatureValidator\SignatureValidator`. Here's what that interface looks like.
 
 ```php
 use Illuminate\Http\Request;
@@ -154,7 +159,7 @@ interface SignatureValidator
 }
 ```
 
-`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. 
+`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.
 
@@ -183,9 +188,9 @@ After creating your own `WebhookProfile` you must register it in the `webhook_pr
 
 ### 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. 
+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. This is done using the `WebhookCall` model. 
+The request will first be stored in the `webhook_calls` table. This is done using the `WebhookCall` model.
 
 Should you want to customize the table name or anything on the storage behavior, you can let the package use an alternative model. A webhook storing model can be specified in the `webhook_model`. Make sure you model extends `Spatie\WebhookClient\Models\WebhookCall`.
 
@@ -203,13 +208,32 @@ class ProcessWebhookJob extends SpatieProcessWebhookJob
     public function handle()
     {
         // $this->webhookCall // contains an instance of `WebhookCall`
-    
+
         // perform the work here
     }
 }
 ```
 
-You should specify the class name of your job in the `process_webhook_job` of the `webhook-client` config file. 
+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 `\Spatie\WebhookClient\WebhookResponse\WebhookResponse`. This is what that interface looks like:
+
+```php
+namespace Spatie\WebhookClient\WebhookResponse;
+
+use Illuminate\Http\Request;
+use Spatie\WebhookClient\WebhookConfig;
+
+interface WebhookResponse
+{
+    public function respondToValidWebhookRequest(Request $request, WebhookConfig $config);
+}
+```
+
+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
 
@@ -224,6 +248,7 @@ return [
             'signature_header_name' => 'Signature-for-app-1',
             'signature_validator' => \Spatie\WebhookClient\SignatureValidator\DefaultSignatureValidator::class,
             'webhook_profile' => \Spatie\WebhookClient\WebhookProfile\ProcessEverythingWebhookProfile::class,
+            'webhook_response' => \Spatie\WebhookClient\WebhookResponse\DefaultResponse::class,
             'webhook_model' => \Spatie\WebhookClient\Models\WebhookCall::class,
             'process_webhook_job' => '',
         ],
@@ -233,6 +258,7 @@ return [
             'signature_header_name' => 'Signature-for-app-2',
             'signature_validator' => \Spatie\WebhookClient\SignatureValidator\DefaultSignatureValidator::class,
             'webhook_profile' => \Spatie\WebhookClient\WebhookProfile\ProcessEverythingWebhookProfile::class,
+            'webhook_response' => \Spatie\WebhookClient\WebhookResponse\DefaultResponse::class,
             'webhook_model' => \Spatie\WebhookClient\Models\WebhookCall::class,
             'process_webhook_job' => '',
         ],
@@ -262,6 +288,7 @@ $webhookConfig = new \Spatie\WebhookClient\WebhookConfig([
     'signature_header_name' => 'Signature',
     'signature_validator' => \Spatie\WebhookClient\SignatureValidator\DefaultSignatureValidator::class,
     'webhook_profile' => \Spatie\WebhookClient\WebhookProfile\ProcessEverythingWebhookProfile::class,
+    'webhook_response' => \Spatie\WebhookClient\WebhookResponse\DefaultResponse::class,
     'webhook_model' => \Spatie\WebhookClient\Models\WebhookCall::class,
     'process_webhook_job' => '',
 ]);

config/webhook-client.php

@@ -32,6 +32,11 @@
              */
             'webhook_profile' => \Spatie\WebhookClient\WebhookProfile\ProcessEverythingWebhookProfile::class,
 
+            /*
+             * This class determines the response on a valid webhook call.
+             */
+            'webhook_response' => \Spatie\WebhookClient\WebhookResponse\DefaultResponse::class,
+
             /*
              * The classname of the model to be used to store call. The class should be equal
              * or extend Spatie\WebhookClient\Models\WebhookCall.

src/Exceptions/InvalidConfig.php

@@ -6,6 +6,7 @@
 use Spatie\WebhookClient\ProcessWebhookJob;
 use Spatie\WebhookClient\SignatureValidator\SignatureValidator;
 use Spatie\WebhookClient\WebhookProfile\WebhookProfile;
+use Spatie\WebhookClient\WebhookResponse\WebhookResponse;
 
 class InvalidConfig extends Exception
 {
@@ -28,6 +29,13 @@ public static function invalidWebhookProfile(string $webhookProfile): InvalidCon
         return new static("`{$webhookProfile}` is not a valid webhook profile class. A valid web hook profile is a class that implements `{$webhookProfileInterface}`.");
     }
 
+    public static function invalidWebhookResponse(string $webhookResponse): InvalidConfig
+    {
+        $webhookResponseInterface = WebhookResponse::class;
+
+        return new static("`{$webhookResponse}` is not a valid webhook response class. A valid webhook response is a class that implements `{$webhookResponseInterface}`.");
+    }
+
     public static function invalidProcessWebhookJob(string $processWebhookJob): InvalidConfig
     {
         $abstractProcessWebhookJob = ProcessWebhookJob::class;

src/WebhookConfig.php

@@ -5,6 +5,7 @@
 use Spatie\WebhookClient\Exceptions\InvalidConfig;
 use Spatie\WebhookClient\SignatureValidator\SignatureValidator;
 use Spatie\WebhookClient\WebhookProfile\WebhookProfile;
+use Spatie\WebhookClient\WebhookResponse\WebhookResponse;
 
 class WebhookConfig
 {
@@ -18,6 +19,8 @@ class WebhookConfig
 
     public WebhookProfile $webhookProfile;
 
+    public WebhookResponse $webhookResponse;
+
     public string $webhookModel;
 
     public string $processWebhookJobClass;
@@ -40,6 +43,11 @@ public function __construct(array $properties)
         }
         $this->webhookProfile = app($properties['webhook_profile']);
 
+        if (! is_subclass_of($properties['webhook_response'], WebhookResponse::class)) {
+            throw InvalidConfig::invalidWebhookResponse($properties['webhook_response']);
+        }
+        $this->webhookResponse = app($properties['webhook_response']);
+
         $this->webhookModel = $properties['webhook_model'];
 
         if (! is_subclass_of($properties['process_webhook_job'], ProcessWebhookJob::class)) {

src/WebhookController.php

@@ -8,8 +8,6 @@ class WebhookController
 {
     public function __invoke(Request $request, WebhookConfig $config)
     {
-        (new WebhookProcessor($request, $config))->process();
-
-        return response()->json(['message' => 'ok']);
+        return (new WebhookProcessor($request, $config))->process();
     }
 }

src/WebhookProcessor.php

@@ -26,12 +26,14 @@ public function process()
         $this->ensureValidSignature();
 
         if (! $this->config->webhookProfile->shouldProcess($this->request)) {
-            return;
+            return $this->createResponse();
         }
 
         $webhookCall = $this->storeWebhook();
 
         $this->processWebhook($webhookCall);
+
+        return $this->createResponse();
     }
 
     protected function ensureValidSignature()
@@ -64,4 +66,9 @@ protected function processWebhook(WebhookCall $webhookCall): void
             throw $exception;
         }
     }
+
+    protected function createResponse()
+    {
+        return $this->config->webhookResponse->respondToValidWebhookRequest($this->request, $this->config);
+    }
 }

src/WebhookResponse/DefaultResponse.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace Spatie\WebhookClient\WebhookResponse;
+
+use Illuminate\Http\Request;
+use Spatie\WebhookClient\WebhookConfig;
+use Symfony\Component\HttpFoundation\Response;
+
+class DefaultResponse implements WebhookResponse
+{
+    public function respondToValidWebhookRequest(Request $request, WebhookConfig $config): Response
+    {
+        return response()->json(['message' => 'ok']);
+    }
+}

src/WebhookResponse/WebhookResponse.php

@@ -0,0 +1,12 @@
+<?php
+
+namespace Spatie\WebhookClient\WebhookResponse;
+
+use Illuminate\Http\Request;
+use Spatie\WebhookClient\WebhookConfig;
+use Symfony\Component\HttpFoundation\Response;
+
+interface WebhookResponse
+{
+    public function respondToValidWebhookRequest(Request $request, WebhookConfig $config): Response;
+}

tests/TestClasses/CustomWebhookResponse.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace Spatie\WebhookClient\Tests\TestClasses;
+
+use Illuminate\Http\Request;
+use Spatie\WebhookClient\WebhookConfig;
+use Spatie\WebhookClient\WebhookResponse\WebhookResponse;
+use Symfony\Component\HttpFoundation\Response;
+
+class CustomWebhookResponse implements WebhookResponse
+{
+    public function respondToValidWebhookRequest(Request $request, WebhookConfig $config): Response
+    {
+        return response()->json(['foo' => 'bar']);
+    }
+}

tests/WebhookConfigTest.php

@@ -8,6 +8,7 @@
 use Spatie\WebhookClient\Tests\TestClasses\ProcessWebhookJobTestClass;
 use Spatie\WebhookClient\WebhookConfig;
 use Spatie\WebhookClient\WebhookProfile\ProcessEverythingWebhookProfile;
+use Spatie\WebhookClient\WebhookResponse\DefaultResponse;
 
 class WebhookConfigTest extends TestCase
 {
@@ -49,6 +50,17 @@ public function it_validates_the_webhook_profile()
         new WebhookConfig($config);
     }
 
+    /** @test */
+    public function it_validates_the_webhook_response()
+    {
+        $config = $this->getValidConfig();
+        $config['webhook_response'] = 'invalid-webhook-response';
+
+        $this->expectException(InvalidConfig::class);
+
+        new WebhookConfig($config);
+    }
+
     /** @test */
     public function it_validates_the_process_webhook_job()
     {
@@ -68,6 +80,7 @@ protected function getValidConfig(): array
             'signature_header_name' => 'Signature',
             'signature_validator' => DefaultSignatureValidator::class,
             'webhook_profile' => ProcessEverythingWebhookProfile::class,
+            'webhook_response' => DefaultResponse::class,
             'webhook_model' => WebhookCall::class,
             'process_webhook_job' => ProcessWebhookJobTestClass::class,
         ];

tests/WebhookControllerTest.php

@@ -8,6 +8,7 @@
 use Illuminate\Support\Facades\Route;
 use Spatie\WebhookClient\Events\InvalidSignatureEvent;
 use Spatie\WebhookClient\Models\WebhookCall;
+use Spatie\WebhookClient\Tests\TestClasses\CustomWebhookResponse;
 use Spatie\WebhookClient\Tests\TestClasses\EverythingIsValidSignatureValidator;
 use Spatie\WebhookClient\Tests\TestClasses\NothingIsValidSignatureValidator;
 use Spatie\WebhookClient\Tests\TestClasses\ProcessNothingWebhookProfile;
@@ -142,6 +143,19 @@ public function it_can_work_with_an_alternative_model()
         $this->assertEquals([], WebhookCall::first()->payload);
     }
 
+    /** @test */
+    public function it_can_respond_with_custom_response()
+    {
+        config()->set('webhook-client.configs.0.webhook_response', CustomWebhookResponse::class);
+
+        $this
+            ->postJson('incoming-webhooks', $this->payload, $this->headers)
+            ->assertSuccessful()
+            ->assertJson([
+                'foo' => 'bar',
+            ]);
+    }
+
     private function determineSignature(array $payload): string
     {
         $secret = config('webhook-client.configs.0.signing_secret');