Signing requests | laravel-webhook-server | Spatie       

 SPATIE  

==

spatie.be/open-source

  [Docs](https://spatie.be/docs)  [Laravel-webhook-server](https://spatie.be/docs/laravel-webhook-server/v4)  Signing requests

 Version   v4      

 Other versions for crawler [v4](https://spatie.be/docs/laravel-webhook-server/v4) 

  Signing requests    
- [ Introduction ](https://spatie.be/docs/laravel-webhook-server/v4/introduction)
- [ Installation and setup ](https://spatie.be/docs/laravel-webhook-server/v4/installation-and-setup)
- [ Sending webhooks ](https://spatie.be/docs/laravel-webhook-server/v4/sending-webhooks)
- [ Signing requests ](https://spatie.be/docs/laravel-webhook-server/v4/signing-requests)
- [ Retrying failed webhooks ](https://spatie.be/docs/laravel-webhook-server/v4/retrying-failed-webhooks)
- [ Transport options ](https://spatie.be/docs/laravel-webhook-server/v4/transport-options)
- [ Events ](https://spatie.be/docs/laravel-webhook-server/v4/events)
- [ Testing webhooks ](https://spatie.be/docs/laravel-webhook-server/v4/testing-webhooks)
- [ Upgrading from v3 ](https://spatie.be/docs/laravel-webhook-server/v4/upgrading)

 Signing requests
================

###  On this page 

1. [ Change or disable the signature header ](#content-change-or-disable-the-signature-header)
2. [ Custom signers ](#content-custom-signers)
3. [ Customize body serialization ](#content-customize-body-serialization)

Share a secret between your application and the receiving application. Pass it to `useSecret()` when creating a webhook. The package adds a `Signature` header calculated over the prepared body:

```
$signature = hash_hmac('sha256', $body, $secret);
```

For JSON requests, the package JSON-encodes the payload once before dispatch. Raw bodies are not JSON-encoded. Every retry sends the same bytes and signature. Standard JSON payloads retain the same default signature as v3.

The receiver should calculate the expected signature over the raw received body and compare it using `hash_equals()`. The default signer does not authenticate the URL, delivery ID, timestamp header, or other headers.

GET webhooks are an exception to body signing: the payload is sent as query parameters and its JSON representation is signed.

Change or disable the signature header
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Change `signature_header_name` in the config file to rename the header. If you need to send an unsigned webhook, call `doNotSign()`; no secret is required and the package does not add its signature header.

Custom signers
--------------------------------------------------------------------------------------------------

Implement `Spatie\WebhookServer\Signer\Signer`:

```
namespace App\WebhookSigners;

use Spatie\WebhookServer\Signer\Signer;

class CustomSigner implements Signer
{
    public function signatureHeaderName(): string
    {
        return 'X-Custom-Signature';
    }

    public function calculateSignature(string $webhookUrl, string $body, string $secret): string
    {
        return hash_hmac('sha256', "{$webhookUrl}\n{$body}", $secret);
    }
}
```

Set the `signer` config key to your class, or select it per call with `signUsing(CustomSigner::class)`.

The body is already serialized. Do not JSON-encode it again. Resolve `DefaultSigner` from Laravel's container if you use it directly and want its configured header name.

Customize body serialization
--------------------------------------------------------------------------------------------------------------------------------------------

To use different JSON options or canonical JSON, extend `Spatie\WebhookServer\CallWebhookJob`, override its protected `generateBody(): string` method, and configure your class in `webhook_job`.

The package prepares that body before dispatch, signs the result, and sends it unchanged across attempts. The override must not depend on worker-only state or the current attempt. HTTP middleware that later changes the body must also update the signature.

 A good
match?
-------------

### What we do best

- All things Laravel
- Custom frontend components
- Building APIs
- AI-powered features
- Simplifying things
- Clean solutions
- Integrating services

### Not our cup of tea

- WordPress themes
- Cutting corners
- Free mockups to win a job
- "Just execute the briefing"

 In short: we'd like to be a **substantial part** of your project.

 [ Get in touch via email ](mailto:info@spatie.be?subject=A%20good%20match%21&body=Tell%20us%20as%20much%20as%20you%20can%20about%0A-%20your%20online%20project%0A-%20your%20planning%0A-%20your%20budget%0A-%20%E2%80%A6%0A%0AAnything%20that%20helps%20us%20to%20start%20straightforward%21)
