README

HMAC-SHA256 HTTP request signing and verification library for PHP. Signs outgoing PSR-7 requests and verifies incoming ones using a shared secret key, with built-in replay attack protection (60-second window).

Installation

composer require ipedis/http-signature

Quick Start

Sign outgoing requests (Guzzle middleware)

use Ipedis\HttpSignature\HttpClient\HttpClient;

class MyApiClient
{
    use HttpClient;

    protected function getSignatureKey(): string
    {
        return 'your-shared-secret-key';
    }
}

$client = new MyApiClient();
$response = $client->getClient()->post('https://api.example.com/webhook', [
    'json' => ['event' => 'user.created'],
]);
// PS-Signature and PS-Timestamp headers are added automatically

Verify incoming requests

use Ipedis\HttpSignature\Signature\Verifier;
use Symfony\Component\HttpFoundation\Request;

class WebhookController
{
    use Verifier;

    protected function getSignatureKey(): string
    {
        return 'your-shared-secret-key';
    }

    public function handle(Request $request): void
    {
        if (!$this->verify($request)) {
            throw new \RuntimeException('Invalid signature');
        }

        // Request is authentic and recent (< 60 seconds)
    }
}

Framework Integration

The library provides injectable services as an alternative to traits, following each framework's dependency injection conventions.

Symfony

The SignedHttpClient is a decorator that wraps any Symfony HttpClientInterface and automatically signs every outgoing request.

Register the services:

# config/services.yaml
services:
    Ipedis\HttpSignature\HttpClient\SignedHttpClient:
        arguments:
            $client: '@http_client'
            $signatureKey: '%env(HTTP_SIGNATURE_KEY)%'

    Ipedis\HttpSignature\Signature\SignatureVerifier:
        arguments:
            $signatureKey: '%env(HTTP_SIGNATURE_KEY)%'

Sign outgoing requests:

use Ipedis\HttpSignature\HttpClient\SignedHttpClient;

class WebhookDispatcher
{
    public function __construct(private SignedHttpClient $client) {}

    public function dispatch(string $url, array $payload): void
    {
        $this->client->request('POST', $url, [
            'json' => $payload,
        ]);
        // PS-Signature and PS-Timestamp headers are added automatically
    }
}

Verify incoming requests:

use Ipedis\HttpSignature\Signature\SignatureVerifier;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\JsonResponse;

class WebhookController
{
    public function __construct(private SignatureVerifier $verifier) {}

    public function __invoke(Request $request): JsonResponse
    {
        if (!$this->verifier->verify($request)) {
            return new JsonResponse(['error' => 'Invalid signature'], 403);
        }

        // Process webhook...
        return new JsonResponse(['status' => 'ok']);
    }
}

Laravel

The library ships with a service provider that auto-registers SignedClientFactory and SignatureVerifier as singletons.

Step 1 — Add your signature key to config:

// config/services.php
return [
    // ...
    'http_signature' => [
        'key' => env('HTTP_SIGNATURE_KEY'),
    ],
];

Step 2 — Register the service provider (auto-discovered if using Laravel package discovery):

// bootstrap/providers.php (Laravel 11+)
return [
    // ...
    Ipedis\HttpSignature\Laravel\HttpSignatureServiceProvider::class,
];

Or in config/app.php for older versions:

'providers' => [
    // ...
    Ipedis\HttpSignature\Laravel\HttpSignatureServiceProvider::class,
],

Sign outgoing requests:

use Ipedis\HttpSignature\HttpClient\SignedClientFactory;

class WebhookDispatcher
{
    public function __construct(private SignedClientFactory $factory) {}

    public function dispatch(string $url, array $payload): void
    {
        $client = $this->factory->create();
        $client->post($url, [
            'json' => $payload,
        ]);
        // PS-Signature and PS-Timestamp headers are added automatically
    }
}

Verify incoming requests:

use Ipedis\HttpSignature\Signature\SignatureVerifier;
use Illuminate\Http\Request;
use Illuminate\Http\JsonResponse;

class WebhookController
{
    public function __construct(private SignatureVerifier $verifier) {}

    public function __invoke(Request $request): JsonResponse
    {
        if (!$this->verifier->verify($request)) {
            return response()->json(['error' => 'Invalid signature'], 403);
        }

        // Process webhook...
        return response()->json(['status' => 'ok']);
    }
}

How It Works

1. A signing string is built: METHOD.URL.TIMESTAMP.BODY
2. An HMAC-SHA256 hash is computed using the shared secret
3. Two headers are added to the request:
   • PS-Timestamp — Unix timestamp
   • PS-Signature — 64-char hex HMAC hash
4. On verification, the signature is recomputed and compared using constant-time hash_equals()
5. Requests older than 60 seconds are rejected (replay protection)

API

Services (recommended)

Traits (legacy)

All traits require implementing getSignatureKey(): string.

Core

Compatibility

Local Development

Requires Docker.

make up        # Start container
make install   # Install dependencies
make qa        # Run full QA suite (rector + pint + phpstan + tests)

Available targets:

Disclaimer

This package is maintained by Ipedis. It is provided as-is under the terms of its license.