spatie/laravel-webhook-client

The package follows a specific sequence when a webhook request is received:

1. Signature Verification: The package checks if the request signature is valid using the configured signature_validator. If invalid, it throws an exception, fires an InvalidWebhookSignatureEvent, and discards the request (it is not stored).
2. Webhook Profile: The request is passed to a WebhookProfile. This class determines if the specific request is interesting enough to be stored and processed. If it returns false, processing stops.
3. Storage: If the profile allows it, the request is stored in the webhook_calls table using a WebhookCall model.
4. Queued Processing: Once stored, the WebhookCall model is passed to a queued job (defined by process_webhook_job). This allows for a fast HTTP response to the sender. If queueing fails, the exception is stored in the exception attribute of the WebhookCall model.
5. Webhook Response: Finally, a WebhookResponse class determines the HTTP response sent back to the sender (defaults to a 200 OK).

Publish the configuration file to config/webhook-client.php to define how webhooks are handled. The package supports multiple webhook receiving endpoints via the configs array.

Key configuration options include:

• signing_secret: The secret used to verify the signature of incoming calls.
• signature_header_name: The header containing the signature.
• signature_validator: The class responsible for verifying the signature (must implement \Spatie\WebhookClient\SignatureValidator\SignatureValidator).
• webhook_profile: Determines if a webhook should be stored and processed.
• webhook_response: Determines the HTTP response sent back to the sender.
• webhook_model: The model used to store webhook calls (must extend \Spatie\WebhookClient\Models\WebhookCall).
• store_headers: An array of headers to store, or * to store all headers.
• process_webhook_job: The class name of the job that will process the webhook (must extend \Spatie\WebhookClient\Jobs\ProcessWebhookJob).
• delete_after_days: Number of days to keep webhook models before deletion (set to null to keep forever).

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

Upgrading from version 2 to version 3 requires database schema updates, configuration changes, and code updates due to renamed classes and moved jobs.

1. Database Migration

You must update your webhook_calls table to include url and headers columns, and ensure the payload column is compatible with JSON. Run the following command to create a migration:

php artisan make:migration add_columns_to_webhook_calls

Then, implement the migration as follows:

Schema::table('webhook_calls', function (Blueprint $table) {
    $table->string('url')->nullable();
    $table->json('headers')->nullable();
    $table->json('payload')->change();
});

2. Configuration Update

Add the store_headers key to each entry in the configs array within your webhook-client configuration file.

3. Code Updates (Renames and Moves)

• Events: The Spatie\WebhookClient\Events\InvalidSignature event has been renamed to Spatie\WebhookClient\Events\InvalidWebhookSignatureEvent. This new event now receives a Spatie\WebhookClient\WebhookConfig instance as a parameter.
• Jobs: The Spatie\WebhookClient\ProcessWebhookJob class has been moved to Spatie\WebhookClient\Jobs\ProcessWebhookJob.

<?php

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

class AddColumnsToWebhookCalls extends Migration
{
    public function up(): void
    {
        Schema::table('webhook_calls', function (Blueprint $table) {
            $table->string('url')->nullable();
            $table->json('headers')->nullable();
            $table->json('payload')->change();
        });
    }

    public function down(): void
    {
        Schema::table('webhook_calls', function (Blueprint $table) {
            $table->dropColumn('url');
            $table->dropColumn('headers');
            $table->text('payload')->change();
        });
    }
}

The DefaultSignatureValidator implements the SignatureValidator interface to verify that incoming webhook requests are authentic. It uses an HMAC SHA256 hash comparison between a signature provided in the request header and a locally computed signature.

Validation Logic:

1. It retrieves the signature from the request header specified by $config->signatureHeaderName.
2. It retrieves the signing secret from $config->signingSecret.
3. It computes a HMAC SHA256 hash of the raw request body ($request->getContent()) using the signing secret.
4. It performs a timing-attack-safe comparison (hash_equals) between the computed signature and the signature from the header.

Requirements:

• A signing_secret must be configured in your webhook profile. If it is empty, an InvalidConfig::signingSecretNotSet() exception is thrown.
• If the signature header is missing from the request, validation fails and returns false.

// The validator uses the following logic internally:
$computedSignature = hash_hmac('sha256', $request->getContent(), $signingSecret);
return hash_equals($computedSignature, $signature);