spatie/laravel-webhook-server

The package signs the payload to prevent tampering. It calculates an HMAC SHA256 signature using the provided secret and the JSON-encoded payload. The resulting signature is sent in the Signature header.

Calculation logic:

$payloadJson = json_encode($payload); 
$signature = hash_hmac('sha256', $payloadJson, $secret);

To skip signing, call doNotSign().

WebhookCall::create()
   ->doNotSign()
    ...
    ->dispatch();

Install the package via Composer and publish the configuration file to your Laravel application.

composer require spatie/laravel-webhook-server

php artisan vendor:publish --provider="Spatie\WebhookServer\WebhookServerServiceProvider"

The DefaultSigner implements the Signer interface to generate HMAC signatures for webhook payloads. It encodes the $payload array into a JSON string and then calculates a sha256 HMAC hash using the provided $secret.

Signature calculation logic:

1. json_encode($payload)
2. hash_hmac('sha256', $payloadJson, $secret)

<?php

// The signature is generated using sha256 HMAC on the JSON-encoded payload
$signature = hash_hmac('sha256', json_encode($payload), $secret);

When writing automated tests, use Bus::fake() to prevent actual webhooks from being sent to external websites. You can then assert that the Spatie\WebhookServer\CallWebhookJob was dispatched.

use Illuminate\\|Support\\Facades\\Bus;
use Spatie\\WebhookServer\\CallWebhookJob;
use Tests\\TestCase;

class TestFile extends TestCase
{
    public function testJobIsDispatched()
    {
        Bus::fake();

        // ... Perform webhook call ...

        Bus::assertDispatched(CallWebhookJob::class);
    }
}

To ensure webhooks are correctly queued without executing them during tests, use Queue::fake(). You can then assert that the Spatie\WebhookServer\CallWebhookJob was pushed to the queue.

use Illuminate\\Support\\Facades\\Queue;
use Spatie\\WebhookServer\\CallWebhookJob;
use Tests\\TestCase;

class TestFile extends TestCase
{
    public function testJobIsQueued()
    {
        Queue::fake();

        // ... Perform webhook call ...

        Queue::assertPushed(CallWebhookJob::class);
    }
}

To send a webhook, use the WebhookCall::create() fluent API. By default, it sends a POST request with a JSON-encoded payload. If you provide a secret via useSecret(), the package adds a Signature header to allow the receiver to verify the payload integrity.

WebhookCall::create()
   ->url('https://other-app.com/webhooks')
   ->payload(['key' => 'value'])
   ->useSecret('sign-using-this-secret')
   ->dispatch();

To help prevent replay attacks, you can enable timestamping by calling useTimestamp(). This adds a Timestamp header to the request. This feature is disabled by default.

WebhookCall::create()
    ->useTimestamp()
    ...
    ->dispatch();

To authenticate both the client and server, use the mutualTls() method. This requires providing certificate and key paths.

WebhookCall::create()
    ->mutualTls(
        certPath: storage_path('path/to/cert.pem'), 
        certPassphrase: 'optional_cert_passphrase', 
        sslKeyPath: storage_path('path/to/key.pem'), 
        sslKeyPassphrase: 'optional_key_passphrase'
    )

You can override default request settings for specific calls:

• HTTP Verb: Use useHttpVerb('get') (defaults to post).
• Extra Headers: Use withHeaders(['Key' => 'Value']).
• Proxy: Use useProxy('http://proxy.server:3128') (follows Guzzle proxy format).
• SSL Verification: Use doNotVerifySsl() to disable SSL certificate verification.

WebhookCall::create()
    ->useHttpVerb('get')
    ->withHeaders(['Another Header' => 'Value'])
    ->useProxy('http://proxy.server:3128')
    ->doNotVerifySsl()
    ...
    ->dispatch();

By default, payloads are JSON encoded. To send a raw string (e.g., XML), use sendRawBody(string $body).

Warning: Due to a type mismatch in the Signer API, you cannot sign raw data requests. You must call doNotSign() when using raw bodies.

WebhookCall::create()
    ->sendRawBody("<root>someXMLContent</root>")
    ->doNotSign()
    ...
    ->dispatch();