Securing WordPress Webhooks with HMAC SHA-256 and Replay Protection

Modern WordPress applications rely heavily on inbound webhooks to coordinate business logic with third-party SaaS platforms. Whether synchronizing payment events from Stripe, subscription lifecycle updates from Paddle, CRM contact updates from HubSpot, or shipping status triggers from ShipStation, webhooks provide the event-driven connective tissue of contemporary web software.

However, exposing an unauthenticated or poorly secured REST API endpoint to receive incoming webhooks introduces severe security vulnerabilities. Because webhook endpoints must remain publicly accessible on the internet to receive incoming HTTP POST requests from external providers, malicious actors can easily discover and flood these routes with spoofed payloads.

If a custom WordPress plugin relies on naive authentication—such as checking for an unencrypted static query string parameter (e.g., ?secret_token=12345), evaluating standard WordPress nonces (which do not apply to server-to-server calls), or blindly trusting the incoming JSON body—an attacker can forge a payment.completed event, granting themselves lifetime access to premium digital products without paying a cent.

The industry standard for securing server-to-server communication is HMAC SHA-256 (Hash-based Message Authentication Code) verification combined with timestamp-based anti-replay mechanisms, rate limiting, and dead-letter queue recovery.

In this exhaustive engineering masterclass, we will examine the cryptographic foundation of HMAC signatures, dissect the risks of timing attacks and payload mutation, compare symmetric and asymmetric signatures, build production PSR-4 webhook dispatchers and receivers in WordPress, implement zero-downtime secret rotation, integrate dead-letter recovery queues, enforce IP allowlisting, and write comprehensive PHPUnit security test suites.

The Threat Landscape of Inbound WordPress Webhooks

When designing webhook receivers, security engineers must defend against five primary attack vectors:

1. Payload Spoofing & Forgery

An attacker sends an HTTP POST request containing forged JSON data (e.g., setting an order status to completed or escalating a user account to administrator). Without cryptographic signature verification, the WordPress receiver has no mechanism to confirm whether the request originated from Stripe or an adversary using cURL.

2. Man-in-the-Middle (MitM) Tampering

Even over TLS/HTTPS, proxies or compromised intermediate network nodes could alter payload parameters (such as changing the shipping recipient address or modifying license entitlement quantities) while in transit.

3. Replay Attacks

An adversary intercepts a legitimate, authentically signed webhook payload (e.g., an account balance credit event) and repeatedly re-transmits the exact same HTTP request to the WordPress endpoint. Because the signature matches the payload, a naive receiver will process the transaction multiple times, crediting the attacker’s balance indefinitely.

4. Side-Channel Timing Attacks

When comparing the computed cryptographic signature against the client-provided header signature using standard PHP string operators (=== or strcmp()), PHP evaluates strings byte-by-byte and terminates comparison on the first mismatched character. By measuring response latencies with microsecond precision over thousands of requests, an attacker can incrementally deduce the correct signature characters, eventually forging valid headers.

5. Denial-of-Service (DoS) & Worker Pool Exhaustion

Third-party webhook senders enforce strict HTTP response timeouts (typically 5 to 15 seconds). If a WordPress webhook handler performs heavy synchronous operations (such as generating PDFs, importing huge datasets, or querying external APIs) inside the receiver thread, PHP worker pools become exhausted, causing legitimate visitor traffic to stall.

Cryptographic Mechanics of HMAC SHA-256

An HMAC (Hash-based Message Authentication Code) utilizes a shared secret key and a cryptographic hash function (SHA-256) to produce a fixed-length 256-bit hexadecimal digest. The sender and receiver share a secret key (known only to both systems).

When the sender dispatches a webhook:

1. The sender captures the current Unix timestamp: $timestamp = time();.
2. The sender formats the signed payload: $signed_payload = $timestamp . '.' . $raw_request_body;.
3. The sender computes the HMAC hash: $signature = hash_hmac('sha256', $signed_payload, $secret_key);.
4. The sender transmits the signature and timestamp in an HTTP header (e.g., X-WPStack-Signature: t=1757283920,v1=9f83...).

When WordPress receives the webhook:

1. The receiver extracts the timestamp (t) and signature (v1) from the header.
2. The receiver validates that abs(time() - $timestamp) <= 300 seconds (Replay Protection).
3. The receiver reads the exact raw body from php://input.
4. The receiver independently calculates: $expected_signature = hash_hmac('sha256', $timestamp . '.' . $raw_body, $secret_key);.
5. The receiver compares signatures using hash_equals($expected_signature, $signature).

Symmetric HMAC SHA-256 vs Asymmetric Public Key Signatures

While symmetric HMAC-SHA256 is the standard used by Stripe, Shopify, GitHub, and Paddle, some enterprise services (e.g. Apple App Store Server Notifications, DocuSign) utilize asymmetric public-key cryptography (RSA-SHA256 or Ed25519 with JSON Web Signatures):

Why Raw Body Preservation is Mandatory

One of the most frequent bugs in webhook implementations is verifying the signature against a reconstructed or parsed JSON array rather than the exact raw byte stream. Consider the following JSON payload sent by a provider:

{"order_id": 4021, "amount": 99.00, "status": "completed"}

If PHP parses this string via json_decode() and subsequently re-encodes it via wp_json_encode(), PHP may reorder keys, format decimal floats (99 instead of 99.00), or alter whitespace escapes:

{"amount":99,"order_id":4021,"status":"completed"}

Because cryptographic hash functions are highly sensitive to even a single bit modification (the Avalanche Effect), the computed signature on the reconstructed string will be completely different, resulting in false-positive verification rejections. Always read the raw byte stream directly via $request->get_body() or file_get_contents('php://input').

Step-by-Step Production Implementation Guide

Step 1: Outbound Webhook Dispatcher Service

If your custom WordPress plugin dispatches webhooks to external microservices or client endpoints, use this centralized WebhookDispatcherService to generate compliant signatures with automatic retry scheduling:

 $payload Event payload.
     * @param string $secret_key Shared HMAC signing secret.
     * @return bool|WP_Error True on HTTP 2xx response, WP_Error on failure.
     */
    public static function dispatch(string $destination_url, array $payload, string $secret_key): bool|WP_Error {
        $timestamp = time();
        $raw_body  = wp_json_encode($payload);

        if (false === $raw_body) {
            return new WP_Error('json_encode_error', 'Failed to serialize webhook payload.');
        }

        // Construct cryptographic signature
        $signature_payload = $timestamp . '.' . $raw_body;
        $signature_hash    = hash_hmac('sha256', $signature_payload, $secret_key);

        // Format header: t=timestamp,v1=signature
        $header_value = sprintf('t=%d,v1=%s', $timestamp, $signature_hash);

        $response = wp_remote_post($destination_url, [
            'timeout'     => 10,
            'redirection' => 0,
            'httpversion' => '1.1',
            'headers'     => [
                'Content-Type'         => 'application/json',
                'User-Agent'           => 'WPStack-Webhook-Engine/1.0',
                self::SIGNATURE_HEADER => $header_value,
            ],
            'body'        => $raw_body,
            'data_format' => 'body',
        ]);

        if (is_wp_error($response)) {
            return $response;
        }

        $status_code = wp_remote_retrieve_response_code($response);
        if ($status_code < 200 || $status_code >= 300) {
            return new WP_Error(
                'http_delivery_error',
                sprintf('Webhook delivery failed with HTTP status code %d', $status_code),
                ['status' => $status_code, 'body' => wp_remote_retrieve_body($response)]
            );
        }

        return true;
    }
}

Step 2: Cryptographic Signature Validator Middleware

The validator parses the signature header, checks timestamp validity, retrieves the raw body, computes the HMAC digest, and validates the signature using constant-time string comparison. It also supports dual-secret rotation:

 $secrets Single secret or array of active secrets for zero-downtime rotation.
     * @return true|WP_Error
     */
    public static function verify_request(WP_REST_Request $request, string|array $secrets): true|WP_Error {
        $header = $request->get_header('x-wpstack-signature') ?: $request->get_header('x_wpstack_signature');

        if (empty($header)) {
            return new WP_Error('missing_signature', 'Missing signature header in request.', ['status' => 401]);
        }

        // Parse header components: t=timestamp,v1=hash
        $parsed = self::parse_signature_header($header);
        if (!$parsed) {
            return new WP_Error('malformed_signature', 'Malformed signature header format.', ['status' => 400]);
        }

        $timestamp = $parsed['timestamp'];
        $signature = $parsed['signature'];

        // Enforce Replay Attack Protection Window
        $current_time = time();
        if (abs($current_time - $timestamp) > self::MAX_TOLERANCE_SECONDS) {
            return new WP_Error('expired_timestamp', 'Webhook timestamp outside allowed tolerance window.', ['status' => 401]);
        }

        // Extract raw request body
        $raw_body = $request->get_body();
        if (empty($raw_body)) {
            return new WP_Error('empty_payload', 'Webhook body cannot be empty.', ['status' => 400]);
        }

        $signed_payload = $timestamp . '.' . $raw_body;
        $secrets_list   = is_array($secrets) ? $secrets : [$secrets];

        $is_valid = false;
        foreach ($secrets_list as $secret) {
            if (empty($secret)) {
                continue;
            }

            $expected_signature = hash_hmac('sha256', $signed_payload, $secret);

            // Constant-time comparison prevents side-channel timing attacks
            if (hash_equals($expected_signature, $signature)) {
                $is_valid = true;
                break;
            }
        }

        if (!$is_valid) {
            return new WP_Error('invalid_signature', 'HMAC signature verification failed.', ['status' => 403]);
        }

        return true;
    }

    /**
     * Parse header format: t=1757283920,v1=9f83...
     */
    private static function parse_signature_header(string $header): ?array {
        $items = explode(',', $header);
        $data  = [];

        foreach ($items as $item) {
            $parts = explode('=', trim($item), 2);
            if (2 === count($parts)) {
                $data[$parts[0]] = $parts[1];
            }
        }

        if (!isset($data['t']) || !isset($data['v1'])) {
            return null;
        }

        return [
            'timestamp' => (int)$data['t'],
            'signature' => (string)$data['v1'],
        ];
    }
}

Step 3: Inbound REST Receiver with Queue Decoupling

The REST controller registers the public endpoint, attaches the validation logic in the permission_callback, records the event to an idempotency ledger, and dispatches an asynchronous Action Scheduler job before returning an immediate 200 OK response:

 WP_REST_Server::CREATABLE,
            'callback'            => [self::class, 'handle_incoming_webhook'],
            'permission_callback' => [self::class, 'validate_webhook_permissions'],
        ]);
    }

    /**
     * Validate HMAC signature in permission_callback before executing handler.
     */
    public static function validate_webhook_permissions(WP_REST_Request $request): bool|WP_Error {
        // Enforce rate limiting prior to cryptographic calculation
        $rate_check = WebhookRateLimiter::check_rate_limit($request);
        if (is_wp_error($rate_check)) {
            return $rate_check;
        }

        // Retrieve active webhook secrets from secure configuration
        $primary_secret   = defined('WPSTACK_WEBHOOK_SECRET') ? WPSTACK_WEBHOOK_SECRET : '';
        $secondary_secret = defined('WPSTACK_WEBHOOK_SECRET_OLD') ? WPSTACK_WEBHOOK_SECRET_OLD : '';

        $active_secrets = array_filter([$primary_secret, $secondary_secret]);
        if (empty($active_secrets)) {
            return new WP_Error('unconfigured_secret', 'Webhook signing secret is not configured on server.', ['status' => 500]);
        }

        return HmacSignatureValidator::verify_request($request, $active_secrets);
    }

    /**
     * Handle webhook delivery: persist audit log and enqueue background processing.
     */
    public static function handle_incoming_webhook(WP_REST_Request $request): WP_REST_Response|WP_Error {
        $raw_body = $request->get_body();
        $payload  = json_decode($raw_body, true);

        if (!is_array($payload) || !isset($payload['event_id'])) {
            return new WP_Error('invalid_payload', 'Payload missing required event_id identifier.', ['status' => 422]);
        }

        $event_id   = sanitize_text_field((string)$payload['event_id']);
        $event_type = sanitize_text_field((string)($payload['event_type'] ?? 'unknown'));

        global $wpdb;
        $table = $wpdb->prefix . 'wpstack_webhook_events';

        // Check for duplicate delivery (Idempotency)
        $existing = $wpdb->get_var($wpdb->prepare(
            "SELECT id FROM {$table} WHERE event_id = %s",
            $event_id
        ));

        if ($existing) {
            // Already processed: return 200 OK without re-enqueuing
            return new WP_REST_Response([
                'status'  => 'duplicate_acknowledged',
                'message' => 'Event was previously received and acknowledged.',
            ], 200);
        }

        // Insert event into ledger
        $wpdb->insert($table, [
            'event_id'     => $event_id,
            'event_type'   => $event_type,
            'payload_json' => $raw_body,
            'status'       => 'pending',
            'received_at'  => current_time('mysql', true),
        ]);

        $log_id = $wpdb->insert_id;

        // Offload execution to Action Scheduler background queue
        if (function_exists('as_enqueue_async_action')) {
            as_enqueue_async_action(
                self::HOOK_PROCESS_WEBHOOK,
                ['log_id' => $log_id, 'event_id' => $event_id],
                'wpstack-webhooks'
            );
        }

        // Return immediate fast response to provider
        return new WP_REST_Response([
            'status'   => 'success',
            'event_id' => $event_id,
            'message'  => 'Webhook received and enqueued for processing.',
        ], 200);
    }

    /**
     * Background Action Scheduler callback.
     */
    public static function execute_background_webhook(int $log_id, string $event_id): void {
        global $wpdb;
        $table = $wpdb->prefix . 'wpstack_webhook_events';

        $event = $wpdb->get_row($wpdb->prepare(
            "SELECT * FROM {$table} WHERE id = %d",
            $log_id
        ));

        if (!$event) {
            return;
        }

        $payload = json_decode($event->payload_json, true);

        try {
            // Execute business logic based on event_type
            do_action('wpstack_webhook_event_' . $event->event_type, $payload);

            // Update status to completed
            $wpdb->update($table, [
                'status'       => 'completed',
                'processed_at' => current_time('mysql', true),
            ], ['id' => $log_id]);

        } catch (Throwable $e) {
            $wpdb->update($table, [
                'status'        => 'failed',
                'error_message' => substr($e->getMessage(), 0, 1000),
                'processed_at'  => current_time('mysql', true),
            ], ['id' => $log_id]);

            throw new RuntimeException(sprintf('Failed to process webhook event %s: %s', $event_id, $e->getMessage()));
        }
    }
}

Step 4: Asymmetric Public Key Verification with OpenSSL

When receiving webhooks from enterprise identity or financial providers that sign events using private RSA or ECDSA keys (such as Apple StoreKit or DocuSign), verify the signature using the provider’s public PEM certificate:

get_header('x-provider-signature');
        if (empty($signature_base64)) {
            return new WP_Error('missing_signature', 'Missing asymmetric signature header.', ['status' => 401]);
        }

        $signature = base64_decode($signature_base64, true);
        if (false === $signature) {
            return new WP_Error('malformed_signature', 'Signature is not valid base64.', ['status' => 400]);
        }

        $raw_body = $request->get_body();
        $public_key = openssl_pkey_get_public($public_key_pem);

        if (false === $public_key) {
            return new WP_Error('invalid_public_key', 'Invalid public key certificate format.', ['status' => 500]);
        }

        // Verify SHA-256 signature against raw body
        $verify_result = openssl_verify($raw_body, $signature, $public_key, OPENSSL_ALGO_SHA256);

        if (1 === $verify_result) {
            return true;
        }

        return new WP_Error('signature_mismatch', 'Asymmetric cryptographic verification failed.', ['status' => 403]);
    }
}

Step 5: Webhook Rate Limiting & IP Allowlisting

Because webhook endpoints are public, they can be targeted by Denial of Service attacks designed to exhaust database connections. We combine IP allowlisting for known providers (Stripe, GitHub) with an in-memory Redis rate limiter:

= self::MAX_REQUESTS_PER_MINUTE) {
            return new WP_Error('rate_limit_exceeded', 'Too many webhook requests from this IP.', [
                'status'  => 429,
                'headers' => ['Retry-After' => 60],
            ]);
        }

        wp_cache_set($cache_key, $current_hits + 1, 'rate_limits', 60);
        return true;
    }

    /**
     * Optional CIDR IP check for dedicated providers.
     */
    public static function is_ip_in_range(string $ip, string $range): bool {
        if (!str_contains($range, '/')) {
            return $ip === $range;
        }
        [$subnet, $bits] = explode('/', $range, 2);
        $ip_long     = ip2long($ip);
        $subnet_long = ip2long($subnet);
        $mask        = -1 << (32 - (int)$bits);
        $subnet_long &= $mask;
        return ($ip_long & $mask) === $subnet_long;
    }

    private static function get_client_ip(): string {
        if (!empty($_SERVER['HTTP_CF_CONNECTING_IP'])) {
            return (string)$_SERVER['HTTP_CF_CONNECTING_IP']; // Cloudflare
        }
        if (!empty($_SERVER['HTTP_X_FORWARDED_FOR'])) {
            $ips = explode(',', (string)$_SERVER['HTTP_X_FORWARDED_FOR']);
            return trim($ips[0]);
        }
        return (string)($_SERVER['REMOTE_ADDR'] ?? '127.0.0.1');
    }
}

Step 6: Dead-Letter Queue (DLQ) & Manual Replay WP-CLI Engine

When background workers encounter unrecoverable business logic exceptions (such as an external ERP endpoint being deleted or a schema mismatch), failed events are quarantined into a Dead-Letter Queue table for administrative inspection and replay:

]
     * : Replay specific event ID.
     *
     * [--all]
     * : Replay all failed events.
     *
     * ## EXAMPLES
     *
     *     wp wpstack webhook replay --event-id=evt_9021
     *     wp wpstack webhook replay --all
     */
    public function replay(array $args, array $assoc_args): void {
        global $wpdb;
        $table = $wpdb->prefix . 'wpstack_webhook_events';

        if (!empty($assoc_args['event-id'])) {
            $event_id = sanitize_text_field($assoc_args['event-id']);
            $events = $wpdb->get_results($wpdb->prepare("SELECT * FROM {$table} WHERE event_id = %s AND status = 'failed'", $event_id));
        } elseif (!empty($assoc_args['all'])) {
            $events = $wpdb->get_results("SELECT * FROM {$table} WHERE status = 'failed' ORDER BY id ASC LIMIT 500");
        } else {
            WP_CLI::error('Please specify --event-id= or --all');
            return;
        }

        if (empty($events)) {
            WP_CLI::success('No failed webhook events found matching criteria.');
            return;
        }

        WP_CLI::log(sprintf('Found %d failed events to replay...', count($events)));

        foreach ($events as $event) {
            $wpdb->update($table, ['status' => 'pending', 'error_message' => null], ['id' => $event->id]);
            if (function_exists('as_enqueue_async_action')) {
                as_enqueue_async_action(
                    WPStackWebhooksWebhookReceiverController::HOOK_PROCESS_WEBHOOK,
                    ['log_id' => $event->id, 'event_id' => $event->event_id],
                    'wpstack-webhooks'
                );
            }
            WP_CLI::log("Re-enqueued event: {$event->event_id}");
        }

        WP_CLI::success('Replay batch successfully dispatched to queue runner!');
    }
}

if (defined('WP_CLI') && WP_CLI) {
    WP_CLI::add_command('wpstack webhook', WebhookDlqCommand::class);
}

Zero-Downtime Secret Key Rotation Strategy

Security compliance frameworks (SOC 2, PCI-DSS) require regular rotation of API secret keys. In a naive implementation, updating the secret key instantly causes incoming webhooks signed with the previous key to fail until the external SaaS provider updates its webhook settings.

To achieve seamless, zero-downtime rotation:

1. Phase 1 (Dual Verification): Define both the current secret and a new secret in wp-config.php:

   define('WPSTACK_WEBHOOK_SECRET', 'new_secret_key_2026');
   define('WPSTACK_WEBHOOK_SECRET_OLD', 'legacy_secret_key_2025');

2. Phase 2 (Provider Update): Update the webhook secret in the external SaaS platform dashboard (Stripe, HubSpot, etc.). During this transition, requests signed with either key are accepted by HmacSignatureValidator.
3. Phase 3 (Cleanup): Once verification logs confirm that all incoming traffic is signed with new_secret_key_2026, remove WPSTACK_WEBHOOK_SECRET_OLD from server configuration.

Layer 4 Defense: Mutual TLS (mTLS) Client Certificate Verification

For enterprise fintech environments (e.g., banking gateways, healthcare HIPAA data pipelines, and ERP transaction systems), relying solely on application-layer HMAC signatures may leave network edge infrastructure vulnerable to DDoS volumetric floods. By establishing Mutual TLS (mTLS) at the reverse proxy (Nginx or Cloudflare Enterprise), the server cryptographically validates the client's X.509 digital certificate during the initial TLS handshake before any HTTP request reaches PHP-FPM.

When mTLS is configured, the external provider presents an X.509 client certificate issued by a trusted Private Certificate Authority (CA). Nginx verifies the certificate against the trusted CA bundle, extracts client identity variables, and passes them as fastcgi environment parameters to WordPress:

# Nginx /etc/nginx/conf.d/webhook-mtls.conf
server {
    listen 443 ssl http2;
    server_name api.wpstack.online;

    ssl_certificate /etc/ssl/certs/wpstack_server.crt;
    ssl_certificate_key /etc/ssl/private/wpstack_server.key;

    # Trusted CA for incoming client webhook certificates
    ssl_client_certificate /etc/ssl/certs/enterprise_partner_ca.crt;
    ssl_verify_client optional; # Enforce strict validation on webhook routes
    ssl_verify_depth 2;

    location /wp-json/wpstack/v1/webhook-receiver {
        if ($ssl_client_verify != "SUCCESS") {
            return 403 "Forbidden: Invalid or Missing Client Certificate";
        }

        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param SSL_CLIENT_VERIFY $ssl_client_verify;
        fastcgi_param SSL_CLIENT_S_DN $ssl_client_s_dn;
        include fastcgi_params;
    }
}

Inside WordPress, our REST API controller checks the forwarded client identity parameters to ensure that only authorized partner certificates can trigger high-value database operations:

 403]
            );
        }

        if (!str_contains($subject_dn, "CN={$expected_common_name}")) {
            return new WP_Error(
                'mtls_unauthorized_subject',
                __('Client certificate Subject DN does not match expected authority.', 'wpstack'),
                ['status' => 403]
            );
        }

        return true;
    }
}

Distributed Token Bucket Rate Limiting with Redis & Lua

When receiving webhooks from enterprise platforms during flash sale events or product launches, a sudden burst of 50,000 webhooks per minute can easily exhaust PHP-FPM worker pools and saturate MySQL connection pools. Rather than using transient MySQL rows for rate limiting, we implement an atomic Token Bucket Rate Limiter in Redis executed via an inline Lua script.

The Token Bucket algorithm allows burst traffic up to a configurable maximum capacity while continuously refilling tokens at a steady rate. Because the entire calculation and state update occur within a single atomic Redis Lua execution, race conditions across distributed WordPress cluster nodes are completely eliminated:

= cost then
    tokens = tokens - cost
    redis.call('HMSET', key, 'tokens', tokens, 'last_refreshed', last_refreshed)
    redis.call('EXPIRE', key, 3600)
    return {1, tokens} -- Allowed: 1, Remaining tokens
else
    redis.call('HMSET', key, 'tokens', tokens, 'last_refreshed', last_refreshed)
    redis.call('EXPIRE', key, 3600)
    return {0, tokens} -- Denied: 0, Available tokens
end
LUA;

    public function __construct(Redis $redis) {
        $this->redis = $redis;
    }

    /**
     * Attempt to consume tokens for an inbound webhook source.
     *
     * @param string $source_identifier IP address or Client ID.
     * @param int $capacity Maximum bucket burst capacity.
     * @param float $refill_rate Tokens added per second.
     * @param int $cost Tokens required for this request.
     * @return bool|WP_Error True if allowed, WP_Error if rate limit exceeded.
     */
    public function consume(
        string $source_identifier,
        int $capacity = 100,
        float $refill_rate = 10.0,
        int $cost = 1
    ): bool|WP_Error {
        $key = "wpstack:ratelimit:webhook:{$source_identifier}";
        $now = microtime(true);

        /** @var array{0: int, 1: float} $result */
        $result = $this->redis->eval(
            self::LUA_TOKEN_BUCKET_SCRIPT,
            [$key, $capacity, $refill_rate, $cost, $now],
            1
        );

        if ((int) $result[0] === 1) {
            return true;
        }

        return new WP_Error(
            'webhook_rate_limit_exceeded',
            sprintf(__('Webhook rate limit exceeded. Bucket capacity: %d. Available tokens: %.2f', 'wpstack'), $capacity, $result[1]),
            ['status' => 429]
        );
    }
}

Production Incident Runbook & Troubleshooting Matrix

Writing Automated Security Tests in PHPUnit

Automated testing verifies that your security layer rejects forged, replayed, expired, and tampered payloads under all edge cases:

namespace WPStackTests;

use WP_UnitTestCase;
use WP_REST_Request;
use WPStackWebhooksHmacSignatureValidator;

class WebhookSecurityTest extends WP_UnitTestCase {
    private string $secret = 'test_secret_key_super_secure_123';

    public function test_valid_signature_is_accepted(): void {
        $payload = ['event_id' => 'evt_101', 'action' => 'user_upgraded'];
        $raw_body = json_encode($payload);
        $timestamp = time();

        $signature = hash_hmac('sha256', $timestamp . '.' . $raw_body, $this->secret);

        $request = new WP_REST_Request('POST', '/wpstack/v1/webhook-receiver');
        $request->set_header('x-wpstack-signature', "t={$timestamp},v1={$signature}");
        $request->set_body($raw_body);

        $result = HmacSignatureValidator::verify_request($request, $this->secret);
        $this->assertTrue($result);
    }

    public function test_tampered_payload_is_rejected(): void {
        $payload = ['event_id' => 'evt_101', 'action' => 'user_upgraded'];
        $raw_body = json_encode($payload);
        $timestamp = time();

        $signature = hash_hmac('sha256', $timestamp . '.' . $raw_body, $this->secret);

        // Tamper with body after signing
        $tampered_body = json_encode(['event_id' => 'evt_101', 'action' => 'user_granted_admin']);

        $request = new WP_REST_Request('POST', '/wpstack/v1/webhook-receiver');
        $request->set_header('x-wpstack-signature', "t={$timestamp},v1={$signature}");
        $request->set_body($tampered_body);

        $result = HmacSignatureValidator::verify_request($request, $this->secret);
        $this->assertWPError($result);
        $this->assertEquals('invalid_signature', $result->get_error_code());
    }

    public function test_expired_timestamp_is_rejected(): void {
        $raw_body = json_encode(['event_id' => 'evt_102']);
        // 10 minutes in past (outside 300s window)
        $expired_timestamp = time() - 600;

        $signature = hash_hmac('sha256', $expired_timestamp . '.' . $raw_body, $this->secret);

        $request = new WP_REST_Request('POST', '/wpstack/v1/webhook-receiver');
        $request->set_header('x-wpstack-signature', "t={$expired_timestamp},v1={$signature}");
        $request->set_body($raw_body);

        $result = HmacSignatureValidator::verify_request($request, $this->secret);
        $this->assertWPError($result);
        $this->assertEquals('expired_timestamp', $result->get_error_code());
    }
}

Building Secure WordPress Integrations with WPStack

Engineering resilient server-to-server webhook infrastructures requires rigorous attention to cryptographic standards, timing attack defenses, background queueing, and replay attack prevention. At WPStack Studio, our security engineers build and audit enterprise WordPress plugins, custom REST API gateways, and financial integrations for high-growth tech companies worldwide.

If your organisation requires secure webhook engineering, REST API hardening, or a comprehensive security architecture review, explore our Custom WordPress Plugin Development Services to consult with our lead security architects.

Frequently asked questions

Aditya Bhimrajka

Aditya Bhimrajka is the Chief Search Systems Architect at MoxSEO, leading research in enterprise technical SEO, knowledge graphs, large-scale indexing physics, and generative engine optimization.