How to Build a PHP Webhook Receiver: Complete Implementation Guide

Building a PHP Webhook Receiver That Handles Real-World Reliability Challenges

Webhook endpoints fail in ways that other API integrations do not. A remote server sends an HTTP POST request to your application when something happens on their end, such as a payment clearing, a shipment being dispatched, or a user action triggering a notification. The challenge is that this call happens outside your control, on the provider's schedule, potentially multiple times, and with payloads you must verify before trusting.

This guide walks through building a PHP webhook receiver that verifies incoming requests securely, acknowledges requests fast enough to avoid provider timeouts, processes payloads without data loss, and handles duplicate deliveries gracefully. The approach is practical and suited for small to medium traffic applications, with clear pointers for scaling when needed.

Why Signature Verification Is Non-Negotiable

Any endpoint that accepts incoming requests without verification is an open door. An attacker who can send requests to your webhook URL can trigger actions in your system by impersonating the payment processor, shipping provider, or any third-party service you rely on. The consequences range from corrupted data to financial losses if an attacker can fake transaction events or trigger duplicate charges.

Every reputable webhook provider signs their requests. Your receiver must verify those signatures before acting on the payload. Without this step, you have no way to distinguish a genuine webhook from a spoofed one.

Security vulnerabilities in webhook receivers follow the same patterns as other PHP application entry points. Understanding the broader landscape of application security helps you identify risks that might otherwise be overlooked. The OWASP Top 10 provides a useful framework for understanding the most common security risks affecting web applications, including those that can affect webhook endpoints.

HMAC-SHA256 Signature Verification in PHP

The most widely used signature scheme is HMAC-SHA256. The provider computes a hash of the raw request body using a shared secret and includes it in an HTTP header, commonly named X-Signature-256 or Stripe-Signature. Your receiver computes the same hash and compares the results.

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_SIGNATURE_256'] ?? '';
$secret = getenv('WEBHOOK_SECRET');
$expected = hash_hmac('sha256', $payload, $secret);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

The hash_equals function performs a timing-safe comparison. This prevents timing attacks where an attacker measures response times to gradually guess the expected signature. Always use hash_equals rather than a direct string comparison when verifying cryptographic signatures in PHP.

Note: Read the raw request body using php://input rather than $_POST. Most webhook providers send JSON payloads, and the raw body gives you the exact bytes that were signed. If you parse the payload through $_POST first, you may lose the original data needed for reliable signature verification.

Proper input validation matters beyond signature verification. Every field from the webhook payload should be validated before your processing logic acts on it. A structured validation checklist helps catch malformed data early and prevents edge cases from causing problems deeper in your application.

Adding Timestamp Checks to Block Replay Attacks

Some providers include a timestamp header alongside the signature. The timestamp is included in the signature computation, and requests with timestamps outside a reasonable window are rejected. This prevents attackers from capturing and replaying valid webhook calls that they have intercepted.

$timestamp = $_SERVER['HTTP_X_TIMESTAMP'] ?? '';
$timestamp_int = (int) $timestamp;

if (abs(time() - $timestamp_int) > 300) {
    http_response_code(401);
    exit('Timestamp too old');
}

$signature = $_SERVER['HTTP_X_SIGNATURE_256'] ?? '';
$expected = hash_hmac('sha256', $timestamp . '.' . $payload, $secret);

The 300-second tolerance accounts for minor clock differences between your server and the provider's infrastructure. Webhooks outside this window are rejected, limiting the window available for replay attacks. Adjust this tolerance based on your provider's documentation and your system's tolerance for delayed deliveries.

Responding Immediately and Processing in the Background

Webhook providers expect a response within a few seconds. If your processing logic is slow, the provider marks the delivery as failed and retries. This creates a cycle where slow processing triggers repeated retries that further strain your system.

The reliable pattern is to acknowledge the webhook immediately, then handle the actual work asynchronously. Your endpoint should verify the signature, store the payload, and return a 200 status code as quickly as possible. The processing happens separately, in a background worker that runs independently.

// Acknowledge immediately
http_response_code(200);
ob_end_clean();

// Store payload for async processing
$payload = file_get_contents('php://input');
$queueDir = '/var/webhooks/queue/';

if (!is_dir($queueDir)) {
    mkdir($queueDir, 0750, true);
}

file_put_contents($queueDir . uniqid('wh_') . '.json', $payload);
flush();

This approach acknowledges the webhook before any business logic runs. The payload sits in a queue directory. A separate background worker reads from that queue and processes each event at its own pace.

Important: Always return a 200 status code after successfully receiving and storing the webhook. Returning an error code triggers the provider to retry, which can result in the same webhook being processed multiple times. The only exception is when you deliberately want a retry, such as when your queue storage is temporarily unavailable.

Handling Duplicate Deliveries with Idempotency

Webhook providers retry failed deliveries. Without explicit handling, the same event can arrive multiple times, leading to duplicate database records, incorrect application state, or in the case of payment events, duplicate charges. Idempotency ensures that processing the same webhook twice produces the same result as processing it once.

The standard approach is to track processed event IDs. Each webhook payload includes a unique identifier, typically in a field like id or event_id. Store these IDs in a database table or a Redis set.

function isEventProcessed(string $eventId): bool
{
    $pdo = getDatabase();
    $stmt = $pdo->prepare('SELECT 1 FROM processed_webhooks WHERE event_id = ? LIMIT 1');
    $stmt->execute([$eventId]);
    return (bool) $stmt->fetch();
}

function markEventProcessed(string $eventId): void
{
    $pdo = getDatabase();
    $stmt = $pdo->prepare('INSERT IGNORE INTO processed_webhooks (event_id, processed_at) VALUES (?, NOW())');
    $stmt->execute([$eventId]);
}

Using INSERT IGNORE for MySQL or ON CONFLICT DO NOTHING for PostgreSQL handles the case where the same event arrives twice before the first insertion completes. The second insert is silently skipped rather than causing an error. This race-condition handling is essential when processing high-volume webhooks or when multiple worker instances run simultaneously.

Combine this with a check at the start of your processing logic:

function processWebhookPayload(array $data): void
{
    $eventId = $data['id'] ?? null;
    
    if ($eventId === null) {
        throw new InvalidArgumentException('Missing event ID');
    }
    
    if (isEventProcessed($eventId)) {
        return; // Already processed, skip silently
    }
    
    // Process the webhook
    handleEvent($data);
    
    // Mark as processed
    markEventProcessed($eventId);
}

This pattern prevents duplicate processing even when the same webhook arrives through different delivery attempts or gets picked up by multiple worker instances at once. It is a fundamental safeguard for any production webhook integration.

Parsing and Validating the Webhook Payload

Once the signature is verified and duplicate checking is in place, parse the JSON payload and validate its structure before acting on it. Never assume the payload is well-formed. Network issues, encoding problems, or provider bugs can send unexpected data to your endpoint.

$payload = file_get_contents('php://input');
$data = json_decode($payload, true);

if (json_last_error() !== JSON_ERROR_NONE) {
    http_response_code(400);
    exit('Invalid JSON');
}

if (!isset($data['id']) || !isset($data['type']) || !isset($data['data'])) {
    http_response_code(400);
    exit('Missing required fields');
}

$eventType = $data['type'];
$eventId = $data['id'];
$eventData = $data['data'];

Validate the event type before processing. Use a switch statement that handles known event types and silently ignores unknown ones rather than throwing an error for unexpected types. This approach prevents your system from breaking when providers add new event types you have not yet accounted for.

switch ($eventType) {
    case 'payment.completed':
        handlePaymentCompleted($eventData, $eventId);
        break;
    case 'payment.failed':
        handlePaymentFailed($eventData, $eventId);
        break;
    case 'subscription.renewed':
        handleSubscriptionRenewed($eventData, $eventId);
        break;
    default:
        // Log unknown events but do not error
        error_log("Unknown webhook event type: " . $eventType);
        break;
}

When handling webhook events that modify database records, always use prepared statements to prevent SQL injection. Even though the data comes from a verified webhook, treating all external input as potentially untrusted is good practice. Validation and sanitization protect your application from edge cases and unexpected formats that could cause problems in your processing logic.

Logging Webhook Activity for Debugging and Auditing

Log every incoming webhook for debugging and auditing purposes. Store the raw payload, headers, event ID, processing result, and any errors that occur. This creates an audit trail that proves invaluable when debugging issues, investigating suspicious activity, or reconstructing application state after an incident.

function logWebhook(
    string $eventId,
    string $eventType,
    string $payload,
    string $headers,
    string $status,
    ?string $errorMessage = null
): void {
    $pdo = getDatabase();
    $stmt = $pdo->prepare('
        INSERT INTO webhook_logs 
        (event_id, event_type, payload, headers, status, error_message, received_at)
        VALUES (?, ?, ?, ?, ?, ?, NOW())
    ');
    $stmt->execute([$eventId, $eventType, $payload, $headers, $status, $errorMessage]);
}

Keeping the raw payload allows you to replay webhook events if processing fails or the database needs rebuilding. The headers log helps debug signature verification issues by showing exactly what was received. Separating these logs from your general application logs makes filtering and searching easier when investigating webhook-specific problems.

Background Processing with a Cron Worker

A simple queue-based webhook processor can run as a cron job that executes every minute, processes queued payloads, and removes them on success. This approach is reliable, requires minimal infrastructure, and works well for small to medium traffic applications.

First, set up the cron job:

# /etc/cron.d/process-webhooks
* * * * * php /var/www/html/process-webhooks.php 2>&1

Then implement the worker script:

<?php

$queueDir = '/var/webhooks/queue/';
$processedDir = '/var/webhooks/processed/';
$lockFile = '/var/webhooks/lock';

// Prevent overlapping runs
if (file_exists($lockFile) && filemtime($lockFile) > time() - 50) {
    exit('Already running');
}
touch($lockFile);

$files = glob($queueDir . 'wh_*.json');

foreach ($files as $file) {
    $payload = file_get_contents($file);
    $data = json_decode($payload, true);
    
    try {
        processWebhookPayload($data);
        rename($file, $processedDir . basename($file));
    } catch (Exception $e) {
        error_log("Webhook processing failed: " . $e->getMessage());
        
        // Move old failed webhooks to failed directory
        if (filemtime($file) < time() - 3600) {
            rename($file, $processedDir . 'failed_' . basename($file));
        }
    }
}

unlink($lockFile);

The lock file prevents overlapping cron runs if processing takes longer than a minute. Failed webhooks move to the failed directory after an hour so they do not block the queue indefinitely. Regular review of the failed directory helps identify patterns in failures and address underlying issues.

Warning: Before testing webhook processing in a production environment, ensure you have recent backups and a clear rollback plan. Processing webhook events can modify application state, and mistakes in your processing logic can lead to unintended changes. Test thoroughly in a staging environment first.

Production Considerations for PHP Webhook Receivers

Moving from a working implementation to a production-ready webhook receiver involves addressing several practical concerns. Taking time to handle these before going live reduces incident risk and simplifies ongoing maintenance.

Queue Storage and Reliability

The filesystem queue shown here works for low-to-medium traffic applications. For higher volumes, a proper message queue offers better reliability, retry semantics, and dead-letter handling. Solutions like RabbitMQ, Beanstalkd, or AWS SQS integrate well with PHP applications and provide features like priority queues, delayed delivery, and programmatic retry policies that a filesystem-based approach cannot easily match.

Monitoring and Error Notifications

Set up monitoring for your webhook queue. If webhooks start accumulating faster than they are processed, or if the error rate climbs, you need to know quickly. Configure alerts for queue depth exceeding thresholds and error rate spikes. A growing queue often signals a processing failure that needs immediate attention.

Testing Your Webhook Implementation

Use your provider's webhook testing tools during development. Tools like the Stripe CLI let you trigger webhooks locally, making it easier to test signature verification and processing logic without going through a full deployment cycle. Testing with real events from your provider is more reliable than constructing test payloads manually, as it ensures your verification logic handles the actual data format correctly.

Securing Admin Interfaces

If your webhook processing includes an admin interface for monitoring or manual intervention, adding two-factor authentication provides an additional security layer. Even if admin credentials are compromised, a second authentication factor significantly reduces the risk of unauthorized access. PHP supports various two-factor authentication methods that can integrate into existing authentication systems.

Related practical reading

These related guides can help you connect this topic with the wider website, server, security, and support decisions around it.

• SSH Config Tips That Save Hours of Time - useful background for related technology decisions

Key Practices for a Reliable PHP Webhook Receiver

A dependable webhook receiver combines several essential practices. Verify signatures using HMAC-SHA256 with timing-safe comparison. Acknowledge requests immediately and handle processing asynchronously. Track processed event IDs to ensure idempotency. Validate payload structure before acting on data. Log all activity to support debugging and auditing.

The background processing pattern with a queue and a worker ensures that slow processing does not cause provider timeouts and that duplicate deliveries do not create duplicate side effects. This architecture handles higher volumes, survives server restarts, and maintains an audit trail for every webhook event.

If you are integrating with webhook providers and want a review of your current implementation or help building a production-ready solution, you can get in touch with details of your setup and requirements.