Signature verification

Signature verification protects your application from forged webhook requests.

RelayKit validates incoming requests before creating an event or dispatching a handler.

Header based signatures

Most providers send a signature in a request header.

class PaymentProvider extends Provider
{
    public function signatureHeader(): string
    {
        return 'X-Payment-Signature';
    }
}

HMAC verification

RelayKit includes an HMAC verifier.

use RelayKit\Verification\HmacVerifier;

public function verifier(): HmacVerifier
{
    return new HmacVerifier(
        secret: config('services.payments.webhook_secret'),
        algorithm: 'sha256'
    );
}

Timestamp tolerance

To prevent replay attacks, set a timestamp tolerance.

'timestamp_tolerance' => 300,

This allows requests signed within the last five minutes.

Local development

Signature verification can be disabled locally, but should never be disabled in production.

'verify_signatures' => env('APP_ENV') !== 'local',

Common failures

• The wrong secret is configured
• The provider signs the raw body but the app signs parsed JSON
• A proxy strips or renames the signature header
• The timestamp is outside the allowed tolerance