Laravel Webhook Client

https://github.com/spatie/laravel-webhook-client
Admin
A Laravel package that facilitates receiving and processing incoming webhooks, with support for...
Tokens:38,742
Snippets:249
Trust Score:10
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install package via Composer

Source: https://github.com/spatie/laravel-webhook-client/blob/main/README.md

Run this command to install the spatie/laravel-webhook-client package using Composer.

```bash
composer require spatie/laravel-webhook-client
```

--------------------------------

### Usage example: handling missing config

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-config-repository.md

Shows how to handle a missing config by checking for null and throwing InvalidConfig::couldNotFindConfig, mirroring the provider's behavior.

```php
$missing = $repo->getConfig('not-registered');

if (is_null($missing)) {
    // no configuration for this name — mirror the provider's behavior:
    throw \Spatie\WebhookClient\Exceptions\InvalidConfig::couldNotFindConfig('not-registered');
}
```

--------------------------------

### Multi-app webhook config example

Source: https://github.com/spatie/laravel-webhook-client/blob/main/README.md

Example config file for supporting two webhook URLs. Each config entry includes name, signing_secret, signature_header_name, signature_validator, webhook_profile, webhook_response, webhook_model, and process_webhook_job. Comments removed for brevity.

```php
return [
    'configs' => [
        [
            'name' => 'webhook-sending-app-1',
            'signing_secret' => 'secret-for-webhook-sending-app-1',
            '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\DefaultRespondsTo::class,
            'webhook_model' => \Spatie\WebhookClient\Models\WebhookCall::class,
            'process_webhook_job' => '',
        ],
        [
            'name' => 'webhook-sending-app-2',
            'signing_secret' => 'secret-for-webhook-sending-app-2',
            '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\DefaultRespondsTo::class,
            'webhook_model' => \Spatie\WebhookClient\Models\WebhookCall::class,
            'process_webhook_job' => '',
        ],
    ],
];
```

--------------------------------

### ProcessWebhookJob example

Source: https://github.com/spatie/laravel-webhook-client/blob/main/README.md

Example job class that extends Spatie's ProcessWebhookJob. Override handle() to perform work using $this->webhookCall, which contains an instance of WebhookCall. Specify this job class in the 'process_webhook_job' config key.

```php
namespace App\Jobs;

use Spatie\WebhookClient\Jobs\ProcessWebhookJob as SpatieProcessWebhookJob;

class ProcessWebhookJob extends SpatieProcessWebhookJob
{
    public function handle()
    {
        // $this->webhookCall // contains an instance of `WebhookCall`

        // perform the work here
    }
}
```

--------------------------------

### Usage example: register and retrieve a config at runtime

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-config-repository.md

Shows how to use the repository to add a new config and retrieve it. The repository is normally internal but can be used at runtime to register or replace configs.

```php
use Spatie\WebhookClient\WebhookConfig;
use Spatie\WebhookClient\WebhookConfigRepository;

$repo = app(WebhookConfigRepository::class);

$repo->addConfig(new WebhookConfig([
    'name' => 'alternative-config',
    'signing_secret' => 'abc123',
    'signature_header_name' => 'Signature',
    'signature_validator' => \Spatie\WebhookClient\SignatureValidator\DefaultSignatureValidator::class,
    'webhook_profile' => \Spatie\WebhookClient\WebhookProfile\ProcessEverythingWebhookProfile::class,
    'webhook_model' => \Spatie\WebhookClient\Models\WebhookCall::class,
    'process_webhook_job' => \App\Jobs\ProcessWebhookJob::class,
]));

$config = $repo->getConfig('alternative-config'); // ?WebhookConfig
```

--------------------------------

### Route::webhooks usage examples

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-controller.md

Usage example showing how to register webhook routes via the route macro. The first call uses the default config, the second uses a named config, and the third allows multiple HTTP methods on one route.

```php
// routes/web.php
Route::webhooks('webhook-receiving-url');                      // POST → WebhookController, config 'default'
Route::webhooks('other-endpoint', 'webhook-sending-app-2');    // named config
Route::webhooks('multi', 'default', ['post', 'put']);          // two methods, one route
```

--------------------------------

### Use WebhookProcessor directly

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-config.md

Demonstrates programmatic (non-route) use by instantiating WebhookProcessor with the current request and a WebhookConfig, then calling process() to handle the webhook. The config keys are the same as in the basic construction example.

```php
$request = request(); // current Illuminate\Http\Request
$webhookConfig = new WebhookConfig([/* ...same keys as above... */]);

$response = (new \Spatie\WebhookClient\WebhookProcessor($request, $webhookConfig))->process();
```

--------------------------------

### Catching webhook exceptions

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/exceptions.md

Example showing how to catch `InvalidMethod`, `InvalidConfig`, and `InvalidWebhookSignature` exceptions in different scenarios: routing setup, config construction, and request processing.

```php
use Spatie\WebhookClient\Exceptions\InvalidConfig;
use Spatie\WebhookClient\Exceptions\InvalidMethod;
use Spatie\WebhookClient\Exceptions\InvalidWebhookSignature;
use Illuminate\Support\Facades\Route;

// 1. InvalidMethod at routing setup time
try {
    Route::webhooks('incoming', 'default', 'options');
} catch (InvalidMethod $error) {
    // "The method options is not allowed."
}

// 2. InvalidConfig during WebhookConfig construction
try {
    new \Spatie\WebhookClient\WebhookConfig($badConfigArray);
} catch (InvalidConfig $error) {
    // message names the offending key/class
}

// 3. InvalidWebhookSignature at request-processing time
try {
    (new \Spatie\WebhookClient\WebhookProcessor($request, $webhookConfig))->process();
} catch (InvalidWebhookSignature $error) {
    // "The signature is invalid." — nothing was stored
}
```

--------------------------------

### Usage example: listening to InvalidWebhookSignatureEvent

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/invalid-webhook-signature-event.md

Example of registering an event listener to observe rejected webhook requests without altering exception handling. Provides access to the request and config for logging or notification.

```php
use Spatie\WebhookClient\Events\InvalidWebhookSignatureEvent;

Event::listen(InvalidWebhookSignatureEvent::class, fn (InvalidWebhookSignatureEvent $event) => {
    // $event->request  — the request that failed signature validation
    // $event->config   — the WebhookConfig in effect

    log('webhook rejected', [
        'url' => $event->request->fullUrl(),
        'header' => $event->config->signatureHeaderName,
    ]);

    // optional: notify an operator; the request itself will NOT be stored
});
```

--------------------------------

### Custom controller using WebhookProcessor

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-controller.md

Example of a custom controller that re-implements the same one-liner using WebhookProcessor. This is the documented 'use without a controller' path for hosts that prefer their own controller.

```php
class MyWebhookController extends Controller
{
    public function __invoke(Request $request, WebhookConfig $config)
    {
        return (new WebhookProcessor($request, $config))->process();
    }
}
```

--------------------------------

### Custom filtering profile

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-profiles.md

Example profile that only processes requests with an event of 'order.placed'. The profile runs after signature validation but before storage.

```php
namespace App\WebhookProfiles;

use Illuminate\Http\Request;
use Spatie\WebhookClient\WebhookProfile\WebhookProfile;

class OrderWebhookProfile implements WebhookProfile
{
    public function shouldProcess(Request $request): bool
    {
        return $request->input()['event'] === 'order.placed';
    }
}
```

--------------------------------

### Migration example for adding columns to webhook_calls

Source: https://github.com/spatie/laravel-webhook-client/blob/main/UPGRADING.md

This migration adds 'url' and 'headers' columns and changes the 'payload' column to JSON in the 'up' method, and reverses these changes in the 'down' method.

```php
<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

class AddColumnsToWebhookCalls extends Migration
{
    /**
     * Run the migrations.
     *
     * @return void
     */
    public function up(): void
    {
        Schema::table('webhook_calls', function (Blueprint $table) {
            $table->string('url')->nullable();
            $table->json('headers')->nullable();
            $table->json('payload')->change();
        });
    }

    /**
     * Reverse the migrations.
     *
     * @return void
     */
    public function down(): void
    {
        Schema::table('webhook_calls', function (Blueprint $table) {
            $table->dropColumn('url');
            $table->dropColumn('headers');
            $table->text('payload')->change();
        });
    }
}
```

--------------------------------

### Subclassing ProcessWebhookJob with handle method

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/process-webhook-job.md

Example subclass that implements the handle method. Access the webhook call via $this->webhookCall, its payload property, and headers() method. Register this class in the config key process_webhook_job.

```php
namespace App\Jobs;

use Spatie\WebhookClient\Jobs\ProcessWebhookJob as SpatieProcessWebhookJob;

class ProcessWebhookJob extends SpatieProcessWebhookJob
{
    public function handle()
    {
        // $this->webhookCall // an instance of Spatie\WebhookClient\Models\WebhookCall

        $payload = $this->webhookCall->payload;   // stored request input
        $headers = $this->webhookCall->headers(); // HeaderBag

        // perform the actual webhook work here
    }
}
```

--------------------------------

### Custom response class AcceptedRespondsToWebhook

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-responses.md

Example of a custom response strategy that returns a 202 Accepted status with a different JSON body. Implement RespondsToWebhook and return a custom response.

```php
namespace App\WebhookResponses;

use Illuminate\Http\Request;
use Spatie\WebhookClient\WebhookConfig;
use Spatie\WebhookClient\WebhookResponse\RespondsToWebhook;
use Symfony\Component\HttpFoundation\Response;

class AcceptedRespondsToWebhook implements RespondsToWebhook
{
    public function respondToValidWebhook(Request $request, WebhookConfig $config): Response
    {
        return response()->json(['status' => 'accepted'], status: 202);
    }
}
```

--------------------------------

### Handle InvalidConfig exception

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-config.md

Shows how to catch an InvalidConfig exception when constructing a WebhookConfig with invalid class references. The example uses a non-existent signature validator class, which triggers the error message shown in the comment.

```php
use Spatie\WebhookClient\Exceptions\InvalidConfig;

try {
    $config = new WebhookConfig([
        'name' => 'bad',
        'signature_validator' => 'some.arbitrary.class',   // not a SignatureValidator
        'webhook_profile' => 'another.arbitrary.class',
        'webhook_model' => WebhookCall::class,
        'process_webhook_job' => SomeJob::class,
    ]);
} catch (InvalidConfig $error) {
    // message: "`some.arbitrary.class` is not a valid signature validator class. ..."
}
```

--------------------------------

### Read stored data and attachments in a job

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-call.md

Shows how to retrieve a stored webhook call and access its headers, payload, and attachments. Use the HeaderBag lookup for headers, the payload property for request input, and getAttachments() to get an array of UploadedFile instances.

```php
use Spatie\WebhookClient\Models\WebhookCall;

$call = WebhookCall::find(1);

$signatureHeader = $call->headers()->get('Signature');   // HeaderBag lookup
$payload = $call->payload;                               // stored request input
$files = $call->getAttachments();                        // UploadedFile[]

foreach ($files as $file) {
    // $file->getClientOriginalName(), $file->getMimeType(), file_get_contents($file->getPathname()) ...
}
```

--------------------------------

### Run migrations

Source: https://github.com/spatie/laravel-webhook-client/blob/main/README.md

Runs the migrations to create the webhook_calls table.

```bash
php artisan migrate
```

--------------------------------

### prunable()

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-call.md

Method to get a query for pruning old WebhookCall records.

```APIDOC
## prunable()

### Description
Returns a query builder for pruning old WebhookCall records based on the `delete_after_days` config. Implements the `MassPrunable` contract for the `model:prune` Artisan command.

### Method
prunable

### Endpoint
WebhookCall::prunable

### Parameters
None.

### Request Example
```php
$query = WebhookCall::prunable();
```

### Response
#### Success Response
- **Builder** - A query builder selecting rows where `created_at` is older than `delete_after_days`.

#### Response Example
```php
$query = WebhookCall::prunable();
```

### Error Handling
- Throws `InvalidConfig::invalidPrunable($days)` when `webhook-client.delete_after_days` is not an integer (including `null`/unset).
```

--------------------------------

### Publish webhook-client configuration

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/configuration.md

Publishes the package configuration file into the consuming application. Run this command to create config/webhook-client.php in the host application.

```bash
php artisan vendor:publish --provider="Spatie\WebhookClient\WebhookClientServiceProvider" --tag="webhook-client-config"
```

--------------------------------

### configurePackage method

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-client-service-provider.md

Declares the package name, config file, and two migration stubs. Published via vendor:publish with tags webhook-client-config and webhook-client-migrations.

```php
public function configurePackage(Package $package): void
{
    $package
        ->name('laravel-webhook-client')
        ->hasConfigFile()
        ->hasMigrations(
            'create_webhook_calls_table',
            'add_attachments_to_webhook_calls_table',
        );
}
```

--------------------------------

### Create migration for webhook_calls table

Source: https://github.com/spatie/laravel-webhook-client/blob/main/UPGRADING.md

Run this artisan command to generate a new migration file for adding columns to the webhook_calls table.

```bash
php artisan make:migration add_columns_to_webhook_calls
```

--------------------------------

### Register webhook routes with Route::webhooks

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-client-service-provider.md

Shows how to register webhook routes using the Route::webhooks macro. The first argument is the URL, the second is the config name (defaults to 'default'), and the third is an array of HTTP methods (defaults to POST). The macro is registered by the service provider at boot.

```php
use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Middleware;

// routes/web.php — the macro was registered by the provider at boot
Route::webhooks('webhook-receiving-url');                              // POST, config 'default'
Route::webhooks('webhook-receiving-url-2', 'webhook-sending-app-2');   // named config
Route::webhooks('incoming-webhooks', 'default', ['post', 'put']);      // multiple methods
```

--------------------------------

### Publish migration file

Source: https://github.com/spatie/laravel-webhook-client/blob/main/README.md

Publishes the migration for the webhook_calls table using the given Artisan command.

```bash
php artisan vendor:publish --provider="Spatie\WebhookClient\WebhookClientServiceProvider" --tag="webhook-client-migrations"
```

--------------------------------

### Use WebhookProcessor without a controller

Source: https://github.com/spatie/laravel-webhook-client/blob/main/README.md

Instantiate WebhookConfig with the required configuration and pass it along with the request to WebhookProcessor::process(). This verifies the signature, calls the web profile, stores the webhook request, and queues the job. The controller provided by the package uses this class under the hood.

```php
$webhookConfig = new \Spatie\WebhookClient\WebhookConfig([
    'name' => 'webhook-sending-app-1',
    'signing_secret' => 'secret-for-webhook-sending-app-1',
    'signature_header_name' => 'Signature',
    'signature_validator' => \Spatie\WebhookClient\SignatureValidator\DefaultSignatureValidator::class,
    'webhook_profile' => \Spatie\WebhookClient\WebhookProfile\ProcessEverythingWebhookProfile::class,
    'webhook_response' => \Spatie\WebhookClient\WebhookResponse\DefaultRespondsTo::class,
    'webhook_model' => \Spatie\WebhookClient\Models\WebhookCall::class,
    'process_webhook_job' => '',
]);

(new \Spatie\WebhookClient\WebhookProcessor($request, $webhookConfig))->process();
```

--------------------------------

### WebhookProcessor constructor

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-processor.md

Constructor that promotes the incoming request and endpoint configuration to protected properties. Both parameters are required.

```php
public function __construct(
    protected Request $request,
    protected WebhookConfig $config
) {
}
```

--------------------------------

### Run tests with Composer

Source: https://github.com/spatie/laravel-webhook-client/blob/main/README.md

Use this command to execute the package's test suite. It runs the tests defined in the composer.json scripts.

```bash
composer test
```

--------------------------------

### Configure delete_after_days for pruning WebhookCall models

Source: https://github.com/spatie/laravel-webhook-client/blob/main/README.md

Set the 'delete_after_days' value in the webhooks config file to control how long WebhookCall models are kept. In this example, models older than 30 days will be deleted when the prune command runs.

```php
return [
    'configs' => [
        // ...
    ],

    'delete_after_days' => 30,
];
```

--------------------------------

### packageBooted() - Register container bindings

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-client-service-provider.md

Registers two container bindings: a scoped `WebhookConfigRepository` built from `config('webhook-client.configs')`, and a `WebhookConfig` binding that resolves the config for the current route, trimming the random suffix when `add_unique_token_to_route_name` is enabled and throwing `InvalidConfig` if not found.

```php
public function packageBooted()
{
    $this->app->scoped(WebhookConfigRepository::class, function () {
        $configRepository = new WebhookConfigRepository();

        collect(config('webhook-client.configs'))
            ->map(fn (array $config) => new WebhookConfig($config))
            ->each(fn (WebhookConfig $webhookConfig) => $configRepository->addConfig($webhookConfig));

        return $configRepository;
    });

    $this->app->bind(WebhookConfig::class, function () {
        $routeName = Route::currentRouteName() ?? '';

        $configName = Str::after($routeName, 'webhook-client-');

        if (config('webhook-client.add_unique_token_to_route_name', false)) {
            $routeNameSuffix = Str::after($routeName, 'webhook-client-');

            $configName = Str::before($routeNameSuffix, '.');
        }

        $webhookConfig = app(WebhookConfigRepository::class)->getConfig($configName);

        if (is_null($webhookConfig)) {
            throw InvalidConfig::couldNotFindConfig($configName);
        }

        return $webhookConfig;
    });
}
```

--------------------------------

### Basic WebhookConfig construction

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-config.md

Creates a WebhookConfig instance with the same shape as one `configs[]` entry. Use this to configure a webhook client programmatically, specifying the signing secret, signature header name, validator, profile, response class, model, and job.

```php
use Spatie\WebhookClient\WebhookConfig;
use Spatie\WebhookClient\Models\WebhookCall;
use Spatie\WebhookClient\SignatureValidator\DefaultSignatureValidator;
use Spatie\WebhookClient\WebhookProfile\ProcessEverythingWebhookProfile;

$webhookConfig = new WebhookConfig([
    'name' => 'webhook-sending-app-1',
    'signing_secret' => 'secret-for-webhook-sending-app-1',
    'signature_header_name' => 'Signature',
    'signature_validator' => DefaultSignatureValidator::class,
    'webhook_profile' => ProcessEverythingWebhookProfile::class,
    'webhook_response' => \Spatie\WebhookClient\WebhookResponse\DefaultRespondsTo::class,
    'webhook_model' => WebhookCall::class,
    'process_webhook_job' => \App\Jobs\ProcessWebhookJob::class,
]);
```

--------------------------------

### Catching InvalidMethod around Route::webhooks

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/errors.md

Example of catching the InvalidMethod exception when using the Route::webhooks macro with an unsupported method. The try block attempts to register webhooks with 'options' as a method, which triggers the exception. The catch block handles the error, noting that 'options' is not allowed.

```php
use Illuminate\Support\Facades\Route;
use Spatie\WebhookClient\Exceptions\InvalidMethod;

try {
    Route::webhooks('incoming-webhooks', 'default', ['post', 'options']);
} catch (InvalidMethod $error) {
    // 'options' is not part of the allowed set
}
```

--------------------------------

### Change webhook route method to get, put, patch, or delete

Source: https://github.com/spatie/laravel-webhook-client/blob/main/README.md

Use these route registrations to change the default 'post' method to another HTTP verb. Each line registers the same URL for a different method. If a sender uses multiple methods, pass an array as shown in the second block.

```php
Route::webhooks('receiving-url-for-app-1', 'webhook-sending-app-1', 'get');
Route::webhooks('receiving-url-for-app-1', 'webhook-sending-app-1', 'put');
Route::webhooks('receiving-url-for-app-1', 'webhook-sending-app-1', 'patch');
Route::webhooks('receiving-url-for-app-1', 'webhook-sending-app-1', 'delete');
```

```php
Route::webhooks('receiving-url-for-app-1', 'webhook-sending-app-1', ['post', 'put']);
```

--------------------------------

### WebhookProcessor process() method

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-processor.md

Runs the webhook processing pipeline: verifies signature, checks profile, stores webhook, dispatches job, and returns response. Throws InvalidWebhookSignature on invalid signature; exceptions from dispatch are stored and rethrown.

```php
public function process(): Response
{
    $this->ensureValidSignature();

    if (! $this->config->webhookProfile->shouldProcess($this->request)) {
        return $this->createResponse();
    }

    $webhookCall = $this->storeWebhook();

    $this->processWebhook($webhookCall);

    return $this->createResponse();
}
```

--------------------------------

### Constructor signature

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/invalid-webhook-signature-event.md

The constructor definition with two required parameters: the rejected request and the WebhookConfig. Both are constructor-promoted to public properties.

```php
public function __construct(
    public Request $request,
    public WebhookConfig $config
) {
}
```

--------------------------------

### WebhookConfigRepository class definition

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-config-repository.md

The full class definition with an array of configs, addConfig method to register a config by name, and getConfig method to retrieve a config by name or return null.

```php
class WebhookConfigRepository
{
    /** @var \Spatie\WebhookClient\WebhookConfig[] */
    protected array $configs;

    public function addConfig(WebhookConfig $webhookConfig)
    {
        $this->configs[$webhookConfig->name] = $webhookConfig;
    }

    public function getConfig(string $name): ?WebhookConfig
    {
        return $this->configs[$name] ?? null;
    }
}
```

--------------------------------

### createResponse(): Create webhook response

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-processor.md

Returns the response from the configured RespondsToWebhook strategy. Default response is a 200 JSON with {"message":"ok"}.

```php
protected function createResponse(): Response
{
    return $this->config->webhookResponse->respondToValidWebhook($this->request, $this->config);
}
```

--------------------------------

### Basic WebhookProcessor usage in a controller

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-processor.md

Use this snippet inside a host controller to process incoming webhook requests. It is the recommended way to route through the WebhookController as documented in endpoints.md. The controller instantiates WebhookProcessor with the request and WebhookConfig and calls process().

```php
use Illuminate\Foundation\Http\Controller;
use Illuminate\Http\Request;
use Spatie\WebhookClient\WebhookConfig;
use Spatie\WebhookClient\WebhookProcessor;

class IncomingWebhookController extends Controller
{
    public function __invoke(Request $request, WebhookConfig $config)
    {
        return (new WebhookProcessor($request, $config))->process();
    }
}
```

--------------------------------

### WebhookProcessor::__construct(Request $request, WebhookConfig $config)

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-processor.md

Constructor for the WebhookProcessor class. It accepts the incoming webhook request and the endpoint configuration, promoting them to protected properties.

```APIDOC
## Constructor

### Description
Creates a new WebhookProcessor instance with the given request and configuration.

### Method
Constructor

### Signature
```php
public function __construct(
    protected Request $request,
    protected WebhookConfig $config
)
```

### Parameters
- **$request** (Illuminate\Http\Request) - Required - The incoming webhook request.
- **$config** (WebhookConfig) - Required - The endpoint configuration.
```

--------------------------------

### getConfig method implementation

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-config-repository.md

The getConfig method implementation. Returns the WebhookConfig registered under the given name, or null if not found.

```php
public function getConfig(string $name): ?WebhookConfig
{
    return $this->configs[$name] ?? null;
}
```

--------------------------------

### Config file contents (config/webhook-client.php)

Source: https://github.com/spatie/laravel-webhook-client/blob/main/README.md

The published configuration file. It defines the default webhook config, signing secret, signature header name, signature validator, webhook profile, webhook response, webhook model, and the process webhook job. Also includes the delete_after_days setting.

```php
<?php

return [
    'configs' => [
        [
            /*
             * This package supports multiple webhook receiving endpoints. If you only have
             * one endpoint receiving webhooks, you can use 'default'.
             */
            'name' => 'default',

            /*
             * We expect that every webhook call will be signed using a secret. This secret
             * is used to verify that the payload has not been tampered with.
             */
            'signing_secret' => env('WEBHOOK_CLIENT_SECRET'),

            /*
             * The name of the header containing the signature.
             */
            'signature_header_name' => 'Signature',

            /*
             *  This class will verify that the content of the signature header is valid.
             *
             * It should implement \Spatie\WebhookClient\SignatureValidator\SignatureValidator
             */
            'signature_validator' => \Spatie\WebhookClient\SignatureValidator\DefaultSignatureValidator::class,

            /*
             * This class determines if the webhook call should be stored and processed.
             */
            'webhook_profile' => \Spatie\WebhookClient\WebhookProfile\ProcessEverythingWebhookProfile::class,

            /*
             * This class determines the response on a valid webhook call.
             */
            'webhook_response' => \Spatie\WebhookClient\WebhookResponse\DefaultRespondsTo::class,

            /*
             * The classname of the model to be used to store webhook calls. The class should
             * be equal or extend Spatie\WebhookClient\Models\WebhookCall.
             */
            'webhook_model' => \Spatie\WebhookClient\Models\WebhookCall::class,

            /*
             * In this array, you can pass the headers that should be stored on
             * the webhook call model when a webhook comes in.
             *
             * To store all headers, set this value to `*`.
             */
            'store_headers' => [

            ],

            /*
             * The class name of the job that will process the webhook request.
             *
             * This should be set to a class that extends \Spatie\WebhookClient\Jobs\ProcessWebhookJob.
             */
            'process_webhook_job' => '',
        ],
    ],

    /*
     * The number of days after which models should be deleted.
     *
     * Set to null if no models should be deleted.
     */
    'delete_after_days' => 30,
];
```

--------------------------------

### Route::webhooks registration for multiple apps

Source: https://github.com/spatie/laravel-webhook-client/blob/main/README.md

Registers webhook routes for multiple apps. Pass the config name as the second parameter to Route::webhooks, matching the 'name' key in the config file.

```php
Route::webhooks('receiving-url-for-app-1', 'webhook-sending-app-1');
Route::webhooks('receiving-url-for-app-2', 'webhook-sending-app-2');
```

--------------------------------

### Schedule model:prune command for WebhookCall

Source: https://github.com/spatie/laravel-webhook-client/blob/main/README.md

Schedule the 'model:prune' Artisan command in routes/console.php, explicitly passing the WebhookCall class. The commented line shows that omitting the model will not work because package models are not used by default.

```php
use Illuminate\Support\Facades\Schedule;
use Spatie\WebhookClient\Models\WebhookCall;

Schedule::command('model:prune', [
    '--model' => [WebhookCall::class],
])->daily();

// This will not work, as models in a package are not used by default
// Schedule::command('model:prune')->daily();
```

--------------------------------

### WebhookConfig constructor with validation

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-config.md

Constructor for WebhookConfig that validates and assigns configuration values from the raw config array. Throws InvalidConfig exceptions for invalid signature validator, webhook profile, webhook response, or process webhook job classes. Uses null coalescing for optional keys like signing_secret and store_headers.

```php
public function __construct(array $properties)
{
    $this->name = $properties['name'];

    $this->signingSecret = $properties['signing_secret'] ?? '';

    $this->signatureHeaderName = $properties['signature_header_name'] ?? '';

    if (! is_subclass_of($properties['signature_validator'], SignatureValidator::class)) {
        throw InvalidConfig::invalidSignatureValidator($properties['signature_validator']);
    }
    $this->signatureValidator = app($properties['signature_validator']);

    if (! is_subclass_of($properties['webhook_profile'], WebhookProfile::class)) {
        throw InvalidConfig::invalidWebhookProfile($properties['webhook_profile']);
    }
    $this->webhookProfile = app($properties['webhook_profile']);

    $webhookResponseClass = $properties['webhook_response'] ?? DefaultRespondsTo::class;
    if (! is_subclass_of($webhookResponseClass, RespondsToWebhook::class)) {
        throw InvalidConfig::invalidWebhookResponse($webhookResponseClass);
    }
    $this->webhookResponse = app($webhookResponseClass);

    $this->webhookModel = $properties['webhook_model'];

    $this->storeHeaders = $properties['store_headers'] ?? [];

    $this->storeAttachments = $properties['store_attachments'] ?? true;

    if (! is_subclass_of($properties['process_webhook_job'], ProcessWebhookJob::class)) {
        throw InvalidConfig::invalidProcessWebhookJob($properties['process_webhook_job']);
    }

    $this->processWebhookJobClass = $properties['process_webhook_job'];
}
```

--------------------------------

### addConfig method signature

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-config-repository.md

The addConfig method signature. Adds or overwrites the entry indexed by the config's name. No return value.

```php
public function addConfig(WebhookConfig $webhookConfig)
```

--------------------------------

### storeWebhook method

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-call.md

Static method to store an incoming webhook. Builds data array from config and request, conditionally adds attachments if the table has the column, and creates a new record.

```php
public static function storeWebhook(WebhookConfig $config, Request $request): WebhookCall
{
    $data = [
        'name' => $config->name,
        'url' => $request->fullUrl(),
        'headers' => static::headersToStore($config, $request),
        'payload' => static::buildPayloadFromRequest($request),
        'exception' => null,
    ];

    if (Schema::hasColumn((new static())->getTable(), 'attachments')) {
        $data['attachments'] = static::buildAttachmentsFromRequest($config, $request);
    }

    return static::create($data);
}
```

--------------------------------

### processUploadedFile() helper

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-call.md

Returns an array with file metadata and base64-encoded content. Used to build attachment entries from uploaded files.

```php
return [
    'originalName' => $file->getClientOriginalName(),
    'mimeType' => $file->getMimeType(),
    'size' => $file->getSize(),
    'error' => $file->getError(),
    'path' => $file->getPathname(),
    'content' => base64_encode(file_get_contents($file->getPathname())),
];
```

--------------------------------

### ProcessWebhookJob constructor

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/process-webhook-job.md

Constructor that promotes the WebhookCall parameter to a public property. The concrete job reads it as $this->webhookCall in handle().

```php
public function __construct(
    public WebhookCall $webhookCall
) {
}
```

--------------------------------

### WebhookProcessor class declaration

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-processor.md

Declares the WebhookProcessor class in the Spatie\WebhookClient namespace.

```php
class WebhookProcessor
```

--------------------------------

### packageRegistered() - Register webhooks route macro

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-client-service-provider.md

Registers the `webhooks` route macro. Validates methods against a whitelist, throws `InvalidMethod` for invalid ones, optionally appends a random token to the route name when `add_unique_token_to_route_name` is enabled, and returns a named route to the `WebhookController`.

```php
public function packageRegistered()
{
    Route::macro('webhooks', function (string $url, string $name = 'default', array|string $methods = 'post') {
        $methods = Arr::wrap($methods);

        foreach ($methods as $method) {
            if (! in_array($method, ['get', 'query', 'post', 'put', 'patch', 'delete'])) {
                throw InvalidMethod::make($method);
            }
        }

        if (config('webhook-client.add_unique_token_to_route_name', false)) {
            $name .= '.' . Str::random(8);
        }

        return Route::match($methods, $url, '\Spatie\WebhookClient\Http\Controllers\WebhookController')
            ->name("webhook-client-{$name}");
    });
}
```

--------------------------------

### Register webhook route with Route::webhooks

Source: https://github.com/spatie/laravel-webhook-client/blob/main/README.md

Use this in your routes file to register a POST route for receiving webhooks. The URL passed to Route::webhooks must match the URL configured in the sending app.

```php
Route::webhooks('webhook-receiving-url');
```

--------------------------------

### ProcessEverythingWebhookProfile class

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-profiles.md

Default profile that always returns true, causing every signature-valid request to be stored and processed.

```php
class ProcessEverythingWebhookProfile implements WebhookProfile
{
    public function shouldProcess(Request $request): bool
    {
        return true;
    }
}
```

--------------------------------

### Interface RespondsToWebhook definition

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-responses.md

Defines the contract for webhook response strategies. Implement this interface to customize the HTTP response for valid webhook requests. The method receives the request and config, and must return a Response.

```php
interface RespondsToWebhook
{
    public function respondToValidWebhook(Request $request, WebhookConfig $config): Response;
}
```

--------------------------------

### WebhookConfigRepository::getConfig(string $name): ?WebhookConfig

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-config-repository.md

Retrieves a WebhookConfig by its name, or returns null if not found. The caller handles the null case.

```APIDOC
## getConfig(string $name): ?WebhookConfig

### Description
Returns the WebhookConfig registered under the given name, or null when no such config exists.

### Method
Public method on `Spatie\WebhookClient\WebhookConfigRepository`

### Parameters

- **$name** (string) - **required** - The name of the config to retrieve.

### Return
?WebhookConfig - The config if found, otherwise null.
```

--------------------------------

### InvalidConfig

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/exceptions.md

Exception thrown when the webhook configuration is invalid.

```APIDOC
## InvalidConfig

### Description
Exception thrown when the webhook configuration is invalid. The message names the offending key or class.

### Method
Constructor

### Signature
`new InvalidConfig($message)`

### Parameters
- **$message** (string) - Required - The exception message.

### Example
```php
use Spatie\WebhookClient\Exceptions\InvalidConfig;

try {
    new \Spatie\WebhookClient\WebhookConfig($badConfigArray);
} catch (InvalidConfig $error) {
    // message names the offending key/class
}
```
```

--------------------------------

### WebhookProfile interface

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-profiles.md

Defines the shouldProcess method that decides whether a request should be stored and processed. Returns true to store and dispatch, false to skip entirely.

```php
interface WebhookProfile
{
    public function shouldProcess(Request $request): bool;
}
```

--------------------------------

### POST, PUT /multi

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-controller.md

The webhooks route macro can be used with multiple HTTP methods. This endpoint accepts both POST and PUT requests using the 'default' config.

```APIDOC
## [POST, PUT] /multi

### Description
Handles incoming webhook requests using the 'default' config. Accepts both POST and PUT methods.

### Method
POST, PUT

### Endpoint
/multi

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- The request body is passed directly to WebhookProcessor. No specific fields are documented.

### Request Example
No specific request body example is provided in the source.

### Response
#### Success Response (200)
- Returns JSON `{"message":"ok"}`

#### Response Example
{
  "message": "ok"
}

### Error Handling
- Invalid signature: `InvalidWebhookSignature` exception propagates, resulting in a 500 response with the framework's default error body.
- Other unhandled exceptions: 500 response with framework default error body.
```

--------------------------------

### Register profile in config

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-profiles.md

Config entry that points the webhook-profile to the custom profile class. The class must implement WebhookProfile.

```php
'webhook_profile' => \App\WebhookProfiles\OrderWebhookProfile::class,
```

--------------------------------

### Config wiring for process_webhook_job

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/process-webhook-job.md

Configuration wiring that registers the concrete job class in the process_webhook_job key. WebhookConfig validates the value with is_subclass_of and throws InvalidConfig::invalidProcessWebhookJob otherwise.

```php
// config/webhook-client.php
return [
    'configs' => [
        [
            'name' => 'default',
            // ...
            'process_webhook_job' => \App\Jobs\ProcessWebhookJob::class,
        ],
    ],
];
```

--------------------------------

### Register custom webhook_response in config

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-responses.md

Configuration entry to register the custom response class in config/webhook-client.php. The 'webhook_response' key must name a class implementing RespondsToWebhook.

```php
// config/webhook-client.php
'webhook_response' => \App\WebhookResponses\AcceptedRespondsToWebhook::class,
```

--------------------------------

### prunable()

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-call.md

Returns a query builder for rows where created_at is older than the configured delete_after_days. Implements the MassPrunable contract for the model:prune command. Throws InvalidConfig::invalidPrunable($days) if the config value is not an integer.

```php
public function prunable()
{
    $days = config('webhook-client.delete_after_days');

    if (! is_int($days)) {
        throw InvalidConfig::invalidPrunable($days);
    }

    return static::where('created_at', '<', now()->subDays($days));
}
```

--------------------------------

### processWebhook(WebhookCall $webhookCall): Dispatch processing job

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-processor.md

Instantiates the configured processWebhookJobClass with the webhook call, clears any previous exception, and dispatches the job. On failure, saves the exception and rethrows it, resulting in a 500 response.

```php
protected function processWebhook(WebhookCall $webhookCall): void
{
    try {
        $job = new $this->config->processWebhookJobClass($webhookCall);

        $webhookCall->clearException();

        dispatch($job);
    } catch (Exception $exception) {
        $webhookCall->saveException($exception);

        throw $exception;
    }
}
```

--------------------------------

### WebhookConfigRepository::addConfig(WebhookConfig $webhookConfig)

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-config-repository.md

Registers a WebhookConfig instance under its name in the repository, overwriting any existing config with the same name.

```APIDOC
## addConfig(WebhookConfig $webhookConfig)

### Description
Adds (or overwrites) a WebhookConfig entry in the repository, indexed by the config's name. Does not return a value.

### Method
Public method on `Spatie\WebhookClient\WebhookConfigRepository`

### Parameters

- **$webhookConfig** (WebhookConfig) - **required** - The config to register.

### Return
void
```

--------------------------------

### storeWebhook(): Store webhook call

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-processor.md

Stores the webhook call using the configured webhook model's static storeWebhook method. Returns the stored WebhookCall model, respecting custom webhook_model classes and tables.

```php
protected function storeWebhook(): WebhookCall
{
    return $this->config->webhookModel::storeWebhook($this->config, $this->request);
}
```

--------------------------------

### Profile that throws on unsupported content type

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-profiles.md

Shows that a profile may throw an exception, e.g. on invalid payloads. In that case nothing is stored and the exception propagates from WebhookProcessor::process.

```php
public function shouldProcess(Request $request): bool
{
    if ($request->header('Content-Type') !== 'application/json') {
        throw new \Exception('unsupported content type');
    }

    return $request->input()['event'] === 'order.placed';
}
```

--------------------------------

### WebhookProfile interface

Source: https://github.com/spatie/laravel-webhook-client/blob/main/README.md

Defines the contract for a webhook profile. Implement shouldProcess(Request $request): bool to determine if an incoming request should be stored and processed. Register your implementation in the 'webhook_profile' config key.

```php
namespace Spatie\WebhookClient\WebhookProfile;

use Illuminate\Http\Request;

interface WebhookProfile
{
    public function shouldProcess(Request $request): bool;
}
```

--------------------------------

### headersToStore(WebhookConfig $config, Request $request): array

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-call.md

Filters request headers based on the storeHeaders config. Returns all headers when storeHeaders is '*', otherwise only headers whose lowercase name is in the lowercased storeHeaders list. Returns an empty array when storeHeaders is an empty array.

```php
public static function headersToStore(WebhookConfig $config, Request $request): array
{
    $headerNamesToStore = $config->storeHeaders;

    if ($headerNamesToStore === '*') {
        return $request->headers->all();
    }

    $headerNamesToStore = array_map(fn (string $headerName) => strtolower($headerName), $headerNamesToStore);

    return collect($request->headers->all())
        ->filter(fn (array $headerValue, string $headerName) => in_array($headerName, $headerNamesToStore))
        ->toArray();
}
```

--------------------------------

### POST /other-endpoint

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-controller.md

The webhooks route macro can be used with a named config. This endpoint uses the 'webhook-sending-app-2' config.

```APIDOC
## [POST] /other-endpoint

### Description
Handles incoming webhook requests using the named config 'webhook-sending-app-2'. The controller delegates to WebhookProcessor.

### Method
POST

### Endpoint
/other-endpoint

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- The request body is passed directly to WebhookProcessor. No specific fields are documented.

### Request Example
No specific request body example is provided in the source.

### Response
#### Success Response (200)
- Returns JSON `{"message":"ok"}`

#### Response Example
{
  "message": "ok"
}

### Error Handling
- Invalid signature: `InvalidWebhookSignature` exception propagates, resulting in a 500 response with the framework's default error body.
- Other unhandled exceptions: 500 response with framework default error body.
```

--------------------------------

### DefaultRespondsTo class implementation

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-responses.md

Default response strategy that returns a 200 OK with JSON body {"message":"ok"}. Used when no custom webhook_response class is configured.

```php
class DefaultRespondsTo implements RespondsToWebhook
{
    public function respondToValidWebhook(Request $request, WebhookConfig $config): Response
    {
        return response()->json(['message' => 'ok']);
    }
}
```

--------------------------------

### POST /webhook-receiving-url

Source: https://github.com/spatie/laravel-webhook-client/blob/main/_autodocs/api-reference/webhook-controller.md

The WebhookController is invoked via the webhooks route macro. It processes incoming webhook requests by delegating to WebhookProcessor. The endpoint accepts POST requests (and optionally other methods) and returns a JSON response.

```APIDOC
## [POST] /webhook-receiving-url

### Description
Handles incoming webhook requests by delegating to WebhookProcessor. The controller is invoked via the `webhooks` route macro.

### Method
POST

### Endpoint
/webhook-receiving-url

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- The request body is passed directly to WebhookProcessor. No specific fields are documented.

### Request Example
No specific request body example is provided in the source.

### Response
#### Success Response (200)
- Returns JSON `{"message":"ok"}`

#### Response Example
{
  "message": "ok"
}

### Error Handling
- Invalid signature: `InvalidWebhookSignature` exception propagates, resulting in a 500 response with the framework's default error body.
- Other unhandled exceptions: 500 response with framework default error body.
```
Tokens:
Raw