Building Webhooks in PHP: Payload Validation, Retries & Idempotency

SEO Metadata

SEO Title Options

1. Building Webhooks in PHP: Payload Validation, Retries
2. Building Webhooks in PHP: Payload: Practical 2026 Guide
3. APIs Playbook: Building Webhooks in PHP: Payload

Meta Description Options

1. Learn Building Webhooks in PHP: Payload Validation, Retries & Idempotency with a practical APIs framework, expert mistakes, implementation steps, examples.
2. Shows how to implement a robust webhook receiver - HMAC signature verification, duplicate detection, and async processing patterns.

URL Slug

building-webhooks-php-payload-validation-retries-idempotency

Focus Keyword

Building Webhooks in PHP: Payload Validation, Retries & Idempotency

Additional LSI Keywords

• APIs
• PHP
• Webhooks
• Idempotency
• Security
• Building Webhooks in PHP: Payload Validation, Retries & Idempotency
• production checklist
• implementation guide
• best practices
• architecture decisions
• testing strategy
• performance impact

Table of Contents

• Article overview
• What Building Webhooks in PHP: Payload Validation, Retries & Idempotency means
• Why it matters now
• Implementation framework
• Practical comparison
• Expert workflow
• Common mistakes
• Media and link plan
• Original technical deep dive
• FAQ
• Structured data
• Conclusion

Article overview

Building Webhooks in PHP: Payload Validation, Retries & Idempotency is the kind of topic that looks simple until it reaches production. Teams usually discover the real cost late: unclear boundaries, weak defaults, hidden maintenance work, and decisions that seemed harmless when the codebase was small.

The problem gets worse when the article, tutorial, or implementation guide only explains the happy path. This guide closes that gap with a practical framework, a comparison table, common mistakes, and a deep technical section you can use while planning real work.

Keep reading for the non-obvious part: the safest implementation is rarely the most impressive-looking one. It is the one your team can debug, test, document, and evolve without turning every future change into archaeology.

Key Takeaways

• Building Webhooks in PHP: Payload Validation, Retries & Idempotency should be evaluated as a production decision, not only as a syntax or tooling choice.
• The best implementation keeps responsibilities visible, with clear ownership, tests, documentation, and rollback paths.
• Search visibility improves when practical depth, structured answers, and expert examples live on the same page.

[IMAGE: A mobile-first technical article layout showing the main concept, decision table, implementation checklist, and FAQ blocks. Alt: Building Webhooks in PHP: Payload Validation, Retries & Idempotency expert guide for APIs]

What Building Webhooks in PHP: Payload Validation, Retries & Idempotency means

Building Webhooks in PHP: Payload Validation, Retries & Idempotency means applying apis knowledge to a concrete engineering decision, then turning that decision into reliable code, documentation, and operational behavior. In practice, it combines the topic's core concepts with trade-off analysis, implementation boundaries, testing strategy, and maintenance discipline.

This is the definition worth optimizing for featured snippets because it avoids hype. It tells the reader what the topic does and what a professional implementation must include.

Why it matters now

The technical web is more crowded than it was a few years ago. Thin tutorials can still get indexed, but they rarely earn trust from senior developers, buyers, AI answer systems, or teams that need production guidance.

For apis topics, the strongest content now has three layers:

• a clear answer for fast scanning
• a practical framework for implementation
• expert context that explains what breaks later

That same structure helps search engines understand the page. It also helps readers decide whether the advice fits their project.

Implementation framework

Use this framework before adopting the approach described in this article.

1. Define the user problem and the production risk.
2. Identify the smallest reliable implementation boundary.
3. Keep configuration, secrets, and environment-specific behavior outside the article's core logic.
4. Add tests for the behavior that would hurt if it regressed.
5. Document the trade-off, not only the final code.
6. Measure the result with logs, metrics, or user-facing outcomes.
7. Revisit the decision after real usage exposes edge cases.

The sequence is deliberately conservative. It keeps the work grounded in outcomes instead of novelty.

[IMAGE: A seven-step implementation framework with discovery, boundary design, configuration, tests, documentation, measurement, and iteration. Alt: Building Webhooks in PHP: Payload Validation, Retries & Idempotency implementation framework]

Practical comparison

This table is intentionally practical. It gives a reviewer something to check before the implementation becomes expensive to change.

Expert workflow

Expert tip: "Treat Building Webhooks in PHP: Payload Validation, Retries & Idempotency as a system boundary. If the next developer cannot find where the decision lives, how it is tested, and when it should be avoided, the implementation is not finished."

A useful workflow is simple:

• Start with the smallest working example.
• Add the constraints that exist in your real project.
• Remove anything that only demonstrates cleverness.
• Write down the failure modes.
• Add links to related decisions so future readers can navigate the topic cluster.

That last point matters for both humans and search systems. A single article can answer a question; a cluster proves authority.

Common mistakes

Mistake 1: Copying a pattern without its context

A pattern that works in a small demo can fail in a real application. The missing context is usually data volume, team experience, deployment process, security requirements, or observability.

Before copying the pattern, ask what assumption made it safe in the original example.

Mistake 2: Putting business logic in the wrong layer

This is the fastest way to make future debugging expensive. In Laravel, PHP, and server-rendered websites, presentation should receive prepared data, not discover rules on its own.

Keep decision logic in models, actions, services, policies, requests, jobs, or documented helpers where it can be tested directly.

Mistake 3: Optimizing for novelty instead of maintainability

Newer tools and language features can be valuable. They can also hide simple behavior behind unfamiliar syntax.

Use the option that makes the next production incident easier to understand.

Mistake 4: Publishing without a measurement plan

If the article describes a performance, SEO, security, or architecture improvement, define how success will be checked. Logs, tests, crawl diagnostics, analytics, and user behavior are all stronger than assumptions.

[IMAGE: A common-mistakes board with context loss, wrong layer, novelty bias, and missing measurement highlighted. Alt: Building Webhooks in PHP: Payload Validation, Retries & Idempotency common mistakes]

Media and link plan

Image placeholders

• [IMAGE: A concept diagram for Building Webhooks in PHP: Payload Validation, Retries & Idempotency with input, decision boundary, implementation, tests, and production feedback. Alt: Building Webhooks in PHP: Payload Validation, Retries & Idempotency concept diagram]
• [IMAGE: A mobile screenshot-style checklist for Building Webhooks in PHP: Payload Validation, Retries & Idempotency. Alt: Building Webhooks in PHP: Payload Validation, Retries & Idempotency mobile checklist]
• [IMAGE: A comparison table visualization for strong versus weak implementation choices. Alt: Building Webhooks in PHP: Payload Validation, Retries & Idempotency comparison table]

Video placeholder

[VIDEO: Insert a 5-8 minute YouTube walkthrough that demonstrates the main decision, the implementation boundary, the test strategy, and the production caveats for Building Webhooks in PHP: Payload Validation, Retries & Idempotency.]

Trustworthy outbound links

• PHP manual - use this as the trust reference for language-level reference.
• Google Search quality guidance - use this as the trust reference for people-first content and E-E-A-T alignment.

Internal linking opportunities

• Internal guide: PHP and AI: Integrating ChatGPT & Claude APIs - use this when readers need a related APIs follow-up.
• Internal guide: Building a PHP SDK: HTTP Client Abstraction - use this when readers need a related APIs follow-up.

Original Technical Deep Dive

Webhooks are not normal API requests.

They are third-party events delivered over HTTP, usually with at-least-once delivery. That means the same event can arrive twice, arrive late, arrive out of order, or be replayed manually by an operator.

The receiver must be boring:

read raw body
verify signature
store event durably
deduplicate by provider event ID
return 2xx quickly
process asynchronously
make side effects idempotent

This guide was reviewed on May 7, 2026 against Stripe webhook and idempotency documentation, GitHub webhook validation documentation, RFC 2104 HMAC, and PHP manual pages for hash_hmac(), hash_equals(), and json_decode().

The short version

Use this receiver contract:

The hard part is not receiving JSON. The hard part is being correct when the provider retries.

Receiver schema

Start with an intake table.

MySQL example:

CREATE TABLE webhook_events (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    provider VARCHAR(40) NOT NULL,
    provider_event_id VARCHAR(190) NOT NULL,
    event_type VARCHAR(190) NOT NULL,
    payload_sha256 CHAR(64) NOT NULL,
    payload_json JSON NOT NULL,
    status VARCHAR(32) NOT NULL DEFAULT 'pending',
    attempts INT UNSIGNED NOT NULL DEFAULT 0,
    last_error TEXT NULL,
    received_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    available_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    processing_started_at TIMESTAMP NULL,
    processed_at TIMESTAMP NULL,
    failed_at TIMESTAMP NULL,
    UNIQUE KEY webhook_events_provider_event_unique (provider, provider_event_id),
    KEY webhook_events_status_available_index (status, available_at),
    KEY webhook_events_type_received_index (event_type, received_at)
);

PostgreSQL is the same idea with jsonb, bigserial, and on conflict.

The unique key is the important part. Application-level "check then insert" code is not enough under concurrent duplicate deliveries.

Read the raw body

Do this first:

<?php

declare(strict_types=1);

$rawBody = file_get_contents('php://input');

if ($rawBody === false || $rawBody === '') {
    http_response_code(400);
    echo 'Empty webhook payload.';
    return;
}

Do not verify signatures against re-encoded JSON.

This is wrong:

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

HMAC signatures are computed over bytes. Whitespace changes, key order changes, Unicode handling, and JSON re-encoding can all change the byte stream.

Verify a GitHub signature

GitHub sends the SHA-256 HMAC in X-Hub-Signature-256 with a sha256= prefix.

<?php

declare(strict_types=1);

final readonly class GitHubWebhookSignature
{
    public function __construct(private string $secret) {}

    public function verify(string $rawBody, ?string $header): bool
    {
        if ($header === null || ! str_starts_with($header, 'sha256=')) {
            return false;
        }

        $expected = 'sha256='.hash_hmac(
            algo: 'sha256',
            data: $rawBody,
            key: $this->secret,
        );

        return hash_equals($expected, $header);
    }
}

Header helper for plain PHP:

function header_value(string $name): ?string
{
    $key = 'HTTP_'.strtoupper(str_replace('-', '_', $name));

    $value = $_SERVER[$key] ?? null;

    return is_string($value) ? $value : null;
}

Usage:

$verified = (new GitHubWebhookSignature($_ENV['GITHUB_WEBHOOK_SECRET']))
    ->verify($rawBody, header_value('X-Hub-Signature-256'));

if (! $verified) {
    http_response_code(403);
    echo 'Invalid signature.';
    return;
}

Use the current SHA-256 header. Do not add new code around GitHub's legacy SHA-1 signature header.

Verify a Stripe signature

Stripe's signature format is different. The header contains timestamp and one or more signatures:

t=1710000000,v1=abcdef...

The signed payload is:

{timestamp}.{raw_body}

Use Stripe's official SDK when the project already has it. If you implement the check yourself, keep it narrow:

<?php

declare(strict_types=1);

final readonly class StripeWebhookSignature
{
    public function __construct(
        private string $secret,
        private int $toleranceSeconds = 300,
    ) {}

    public function verify(string $rawBody, ?string $header): bool
    {
        if ($header === null) {
            return false;
        }

        $parts = $this->parseHeader($header);
        $timestamp = isset($parts['t'][0]) ? (int) $parts['t'][0] : 0;
        $signatures = $parts['v1'] ?? [];

        if ($timestamp <= 0 || $signatures === []) {
            return false;
        }

        if (abs(time() - $timestamp) > $this->toleranceSeconds) {
            return false;
        }

        $signedPayload = $timestamp.'.'.$rawBody;
        $expected = hash_hmac('sha256', $signedPayload, $this->secret);

        foreach ($signatures as $signature) {
            if (hash_equals($expected, $signature)) {
                return true;
            }
        }

        return false;
    }

    /**
     * @return array<string, list<string>>
     */
    private function parseHeader(string $header): array
    {
        $parts = [];

        foreach (explode(',', $header) as $segment) {
            [$key, $value] = array_pad(explode('=', trim($segment), 2), 2, '');

            if ($key !== '' && $value !== '') {
                $parts[$key][] = $value;
            }
        }

        return $parts;
    }
}

Provider-specific details matter. Do not make one generic verifier unless it can model each provider's exact signature base string, timestamp rules, and header format.

Decode JSON after verification

[IMAGE: Supporting visual 1 for Building Webhooks in PHP: Payload Validation, Retries & Idempotency, showing Building Webhooks in PHP: Payload Validation, Retries & Idempotency decisions, examples, and PHP, APIs, Webhooks. Alt: Building Webhooks in PHP: Payload Validation, Retries & Idempotency building-webhooks-php-payload-validation-retries-idempotency visual 1]

[IMAGE: Supporting visual 1 for Building Webhooks in PHP: Payload Validation, Retries & Idempotency, showing Building Webhooks in PHP: Payload Validation, Retries & Idempotency decisions, examples, and PHP, APIs, Webhooks. Alt: Building Webhooks in PHP: Payload Validation, Retries & Idempotency building-webhooks-php-payload-validation-retries-idempotency visual 1]

After signature verification:

try {
    $payload = json_decode(
        json: $rawBody,
        associative: true,
        depth: 512,
        flags: JSON_THROW_ON_ERROR,
    );
} catch (JsonException) {
    http_response_code(400);
    echo 'Invalid JSON.';
    return;
}

if (! is_array($payload)) {
    http_response_code(400);
    echo 'Payload must be a JSON object.';
    return;
}

Then extract only the provider fields you need:

$eventId = $payload['id'] ?? null;
$eventType = $payload['type'] ?? null;

if (! is_string($eventId) || ! is_string($eventType)) {
    http_response_code(400);
    echo 'Missing event metadata.';
    return;
}

Do not pass arbitrary JSON deep into your domain. Translate it at the edge.

Store before processing

Webhook endpoints should not do slow work inline. Store the event first.

<?php

declare(strict_types=1);

final readonly class WebhookEventStore
{
    public function __construct(private PDO $pdo) {}

    /**
     * Returns true when this is the first delivery of the provider event.
     *
     * @param array<string, mixed> $payload
     */
    public function record(
        string $provider,
        string $eventId,
        string $eventType,
        string $rawBody,
        array $payload,
    ): bool {
        $statement = $this->pdo->prepare(
            'INSERT INTO webhook_events (
                provider,
                provider_event_id,
                event_type,
                payload_sha256,
                payload_json
            ) VALUES (
                :provider,
                :provider_event_id,
                :event_type,
                :payload_sha256,
                :payload_json
            )
            ON DUPLICATE KEY UPDATE
                received_at = received_at',
        );

        $statement->execute([
            'provider' => $provider,
            'provider_event_id' => $eventId,
            'event_type' => $eventType,
            'payload_sha256' => hash('sha256', $rawBody),
            'payload_json' => json_encode($payload, JSON_THROW_ON_ERROR),
        ]);

        return $statement->rowCount() === 1;
    }
}

For MySQL, the no-op duplicate update prevents duplicate insert failure from becoming a 500. For PostgreSQL, use:

ON CONFLICT (provider, provider_event_id) DO NOTHING

The endpoint can now acknowledge duplicates safely:

$isNew = $events->record(
    provider: 'stripe',
    eventId: $eventId,
    eventType: $eventType,
    rawBody: $rawBody,
    payload: $payload,
);

http_response_code($isNew ? 202 : 200);
echo $isNew ? 'Accepted.' : 'Already received.';

Returning 2xx for a duplicate is correct. You already have the event.

Complete receiver

Plain PHP endpoint:

<?php

declare(strict_types=1);

require __DIR__.'/../bootstrap.php';

$rawBody = file_get_contents('php://input');

if ($rawBody === false || $rawBody === '') {
    http_response_code(400);
    echo 'Empty webhook payload.';
    return;
}

$signature = new GitHubWebhookSignature($_ENV['GITHUB_WEBHOOK_SECRET']);

if (! $signature->verify($rawBody, header_value('X-Hub-Signature-256'))) {
    http_response_code(403);
    echo 'Invalid signature.';
    return;
}

try {
    $payload = json_decode($rawBody, true, 512, JSON_THROW_ON_ERROR);
} catch (JsonException) {
    http_response_code(400);
    echo 'Invalid JSON.';
    return;
}

if (! is_array($payload)) {
    http_response_code(400);
    echo 'Payload must be an object.';
    return;
}

$eventId = header_value('X-GitHub-Delivery');
$eventType = header_value('X-GitHub-Event');

if ($eventId === null || $eventType === null) {
    http_response_code(400);
    echo 'Missing GitHub event headers.';
    return;
}

$isNew = $eventStore->record(
    provider: 'github',
    eventId: $eventId,
    eventType: $eventType,
    rawBody: $rawBody,
    payload: $payload,
);

if ($isNew) {
    $queue->dispatch('ProcessWebhookEvent', [
        'provider' => 'github',
        'event_id' => $eventId,
    ]);
}

http_response_code(202);
echo 'Accepted.';

This handler does not clone repositories, send emails, resize images, call Stripe, or update search indexes. It verifies, stores, queues, and returns.

Worker processing

A worker claims pending events and processes them.

<?php

declare(strict_types=1);

final readonly class WebhookWorker
{
    public function __construct(
        private PDO $pdo,
        private WebhookDispatcher $dispatcher,
    ) {}

    public function processNext(): void
    {
        $this->pdo->beginTransaction();

        try {
            $event = $this->claimNextEvent();

            if ($event === null) {
                $this->pdo->commit();

                return;
            }

            $this->pdo->commit();
        } catch (Throwable $exception) {
            $this->pdo->rollBack();

            throw $exception;
        }

        $this->processClaimedEvent($event);
    }

    /**
     * @return array<string, mixed>|null
     */
    private function claimNextEvent(): ?array
    {
        $event = $this->pdo
            ->query(
                "SELECT *
                 FROM webhook_events
                 WHERE status = 'pending'
                   AND available_at <= CURRENT_TIMESTAMP
                 ORDER BY received_at
                 LIMIT 1
                 FOR UPDATE",
            )
            ->fetch(PDO::FETCH_ASSOC);

        if (! is_array($event)) {
            return null;
        }

        $statement = $this->pdo->prepare(
            "UPDATE webhook_events
             SET status = 'processing',
                 attempts = attempts + 1,
                 processing_started_at = CURRENT_TIMESTAMP
             WHERE id = :id",
        );

        $statement->execute(['id' => $event['id']]);

        return $event;
    }

    /**
     * @param array<string, mixed> $event
     */
    private function processClaimedEvent(array $event): void
    {
        try {
            $payload = json_decode(
                (string) $event['payload_json'],
                true,
                512,
                JSON_THROW_ON_ERROR,
            );

            if (! is_array($payload)) {
                throw new RuntimeException('Stored payload is not a JSON object.');
            }

            $this->dispatcher->dispatch(
                provider: (string) $event['provider'],
                eventType: (string) $event['event_type'],
                payload: $payload,
            );

            $this->markProcessed((int) $event['id']);
        } catch (Throwable $exception) {
            $this->markRetryableFailure((int) $event['id'], (int) $event['attempts'], $exception);
        }
    }
}

The exact queue can be Redis, Symfony Messenger, Laravel queues, SQS, RabbitMQ, or a database queue. The design does not change: durable intake first, async processing second.

Retry policy

Do not retry every failure the same way.

Backoff example:

private function markRetryableFailure(int $id, int $attempts, Throwable $exception): void
{
    $nextAttempts = $attempts + 1;

    if ($nextAttempts >= 10) {
        $statement = $this->pdo->prepare(
            "UPDATE webhook_events
             SET status = 'failed',
                 last_error = :error,
                 failed_at = CURRENT_TIMESTAMP
             WHERE id = :id",
        );
    } else {
        $delaySeconds = min(3600, 2 ** $nextAttempts);

        $statement = $this->pdo->prepare(
            "UPDATE webhook_events
             SET status = 'pending',
                 last_error = :error,
                 available_at = DATE_ADD(CURRENT_TIMESTAMP, INTERVAL {$delaySeconds} SECOND)
             WHERE id = :id",
        );
    }

    $statement->execute([
        'id' => $id,
        'error' => $exception::class.': '.$exception->getMessage(),
    ]);
}

For PostgreSQL, replace DATE_ADD with interval arithmetic.

The retry limit is product-specific. Payment state sync may deserve long retries and operator alerts. A marketing analytics webhook may be safe to fail after a short window.

Idempotent business logic

Webhook event deduplication is not enough.

This prevents processing the same provider event twice:

UNIQUE KEY webhook_events_provider_event_unique (provider, provider_event_id)

It does not prevent two different events from trying to create the same local record.

Use business-level unique constraints too:

CREATE TABLE external_payments (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    provider VARCHAR(40) NOT NULL,
    provider_payment_id VARCHAR(190) NOT NULL,
    invoice_id BIGINT UNSIGNED NOT NULL,
    amount_cents INT UNSIGNED NOT NULL,
    currency CHAR(3) NOT NULL,
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    UNIQUE KEY external_payments_provider_payment_unique (provider, provider_payment_id)
);

Handler:

final readonly class PaymentSucceededHandler
{
    public function __construct(private PDO $pdo) {}

    /**
     * @param array<string, mixed> $payload
     */
    public function handle(array $payload): void
    {
        $payment = $payload['data']['object'] ?? null;

        if (! is_array($payment)) {
            throw new RuntimeException('Payment object missing.');
        }

        $providerPaymentId = (string) ($payment['id'] ?? '');
        $invoiceId = (int) ($payment['metadata']['invoice_id'] ?? 0);

        if ($providerPaymentId === '' || $invoiceId <= 0) {
            throw new RuntimeException('Payment payload missing required identifiers.');
        }

        $this->pdo->beginTransaction();

        try {
            $insert = $this->pdo->prepare(
                'INSERT IGNORE INTO external_payments (
                    provider,
                    provider_payment_id,
                    invoice_id,
                    amount_cents,
                    currency
                ) VALUES (
                    :provider,
                    :provider_payment_id,
                    :invoice_id,
                    :amount_cents,
                    :currency
                )',
            );

            $insert->execute([
                'provider' => 'stripe',
                'provider_payment_id' => $providerPaymentId,
                'invoice_id' => $invoiceId,
                'amount_cents' => (int) $payment['amount_received'],
                'currency' => strtoupper((string) $payment['currency']),
            ]);

            if ($insert->rowCount() === 1) {
                $this->markInvoicePaid($invoiceId, $providerPaymentId);
            }

            $this->pdo->commit();
        } catch (Throwable $exception) {
            $this->pdo->rollBack();

            throw $exception;
        }
    }

    private function markInvoicePaid(int $invoiceId, string $providerPaymentId): void
    {
        $statement = $this->pdo->prepare(
            "UPDATE invoices
             SET status = 'paid',
                 paid_provider_payment_id = :provider_payment_id
             WHERE id = :invoice_id
               AND status <> 'paid'",
        );

        $statement->execute([
            'invoice_id' => $invoiceId,
            'provider_payment_id' => $providerPaymentId,
        ]);
    }
}

That gives two safety rails:

• duplicate webhook event is skipped at intake;
• duplicate payment object is skipped at business persistence.

Do not trust exactly-once delivery. Build for at-least-once delivery.

Ordering

Providers do not guarantee that your business state will receive events in the order your code wishes.

[IMAGE: Supporting visual 2 for Building Webhooks in PHP: Payload Validation, Retries & Idempotency, showing Building Webhooks in PHP: Payload Validation, Retries & Idempotency decisions, examples, and PHP, APIs, Webhooks. Alt: Building Webhooks in PHP: Payload Validation, Retries & Idempotency building-webhooks-php-payload-validation-retries-idempotency visual 2]

Bad:

if ($eventType === 'subscription.deleted') {
    $subscription->delete();
}

if ($eventType === 'subscription.updated') {
    $subscription->updateFromPayload($payload);
}

If an older update arrives after delete, the subscription can be recreated incorrectly.

Better patterns:

• Store provider object IDs and event timestamps.
• Ignore events older than the current local version.
• Fetch current provider state for important objects.
• Make state transitions explicit.
• Prefer upserts keyed by provider object IDs.

[IMAGE: Supporting visual 2 for Building Webhooks in PHP: Payload Validation, Retries & Idempotency, showing Building Webhooks in PHP: Payload Validation, Retries & Idempotency decisions, examples, and PHP, APIs, Webhooks. Alt: Building Webhooks in PHP: Payload Validation, Retries & Idempotency building-webhooks-php-payload-validation-retries-idempotency visual 2]

Example:

if ($eventCreatedAt <= $subscription->provider_updated_at) {
    return;
}

$subscription->syncFromProviderPayload($payload);

For payments and subscriptions, the source of truth is usually the provider object state, not the order of webhook deliveries.

Security checklist

For every webhook endpoint:

• Use HTTPS only.
• Use a provider-specific secret per environment.
• Verify the signature before JSON parsing or processing.
• Verify the exact raw request body.
• Use hash_equals() for signature comparison.
• Check timestamp tolerance when the provider signs one.
• Reject unsigned requests.
• Do not log full payloads by default.
• Do not expose provider secrets in error messages.
• Rate limit obvious abuse, but do not block legitimate provider retry bursts.
• Exclude CSRF only for the webhook route, not globally.
• Store enough delivery metadata for incident review.

CSRF tokens protect browser sessions. Webhook providers cannot send your CSRF token. Signature verification is the control that matters for webhooks.

Testing

Test signature verification with known fixtures.

GitHub publishes a simple fixture in its docs. Use it:

it('verifies a GitHub webhook signature', function (): void {
    $verifier = new GitHubWebhookSignature("It's a Secret to Everybody");

    $verified = $verifier->verify(
        rawBody: 'Hello, World!',
        header: 'sha256=757107ea0eb2509fc211221cce984b8a37570b6d7586c22c46f4379c8b043e17',
    );

    expect($verified)->toBeTrue();
});

Test duplicate intake:

it('stores a webhook event only once', function (): void {
    $store = new WebhookEventStore($pdo);

    $payload = ['id' => 'evt_1', 'type' => 'payment.succeeded'];

    expect($store->record('stripe', 'evt_1', 'payment.succeeded', json_encode($payload), $payload))
        ->toBeTrue();

    expect($store->record('stripe', 'evt_1', 'payment.succeeded', json_encode($payload), $payload))
        ->toBeFalse();
});

Test idempotent business side effects:

it('does not mark the same provider payment twice', function (): void {
    $handler = new PaymentSucceededHandler($pdo);
    $payload = paymentSucceededPayload('pi_123', invoiceId: 42);

    $handler->handle($payload);
    $handler->handle($payload);

    expect(countPaymentsForProviderId($pdo, 'pi_123'))->toBe(1);
});

Test failure classification:

• invalid signature returns 403;
• malformed JSON returns 400;
• duplicate event returns 2xx;
• intake database failure returns 500;
• worker transient failure schedules retry;
• worker permanent failure records failure;
• unknown event type is ignored or recorded explicitly.

Observability

Store enough to debug without dumping secrets:

Useful metrics:

• webhook intake count by provider and event type;
• signature failure count;
• duplicate count;
• worker processing latency;
• retry count;
• dead-letter count;
• oldest pending event age.

[IMAGE: Supporting visual 3 for Building Webhooks in PHP: Payload Validation, Retries & Idempotency, showing Building Webhooks in PHP: Payload Validation, Retries & Idempotency decisions, examples, and PHP, APIs, Webhooks. Alt: Building Webhooks in PHP: Payload Validation, Retries & Idempotency building-webhooks-php-payload-validation-retries-idempotency visual 3]

Alert on failed important events and old pending events. A webhook endpoint can return 202 all day while workers are stuck.

Production checklist

Before shipping:

• The endpoint reads raw body once.
• Signature verification happens before JSON parsing.
• Provider secrets are separate per environment.
• Duplicate provider event IDs are protected by a unique constraint.
• Business side effects have their own idempotency keys or unique constraints.
• The endpoint stores durably before returning 2xx.
• Slow work runs in a worker.
• Worker retries are bounded and visible.
• Failed events can be replayed safely.
• Unknown event types are recorded, not silently lost.
• Tests cover invalid signature, duplicate delivery, replay window, and worker retry.
• Logs contain event IDs and hashes, not secrets or full sensitive payloads.

[IMAGE: Supporting visual 3 for Building Webhooks in PHP: Payload Validation, Retries & Idempotency, showing Building Webhooks in PHP: Payload Validation, Retries & Idempotency decisions, examples, and PHP, APIs, Webhooks. Alt: Building Webhooks in PHP: Payload Validation, Retries & Idempotency building-webhooks-php-payload-validation-retries-idempotency visual 3]

Webhook correctness is about treating every delivery as unreliable input. Verify it, store it, deduplicate it, and make the actual business operation safe to run more than once.

FAQ

What is Building Webhooks in PHP: Payload Validation, Retries & Idempotency?

Building Webhooks in PHP: Payload Validation, Retries & Idempotency is a practical apis topic that should be evaluated through implementation scope, production risk, testing, documentation, and long-term maintainability.

When should a team use Building Webhooks in PHP: Payload Validation, Retries & Idempotency?

Use Building Webhooks in PHP: Payload Validation, Retries & Idempotency when it solves a real project constraint, improves clarity, or reduces operational risk. Avoid it when it only adds novelty or hides behavior from future maintainers.

What is the biggest risk with Building Webhooks in PHP: Payload Validation, Retries & Idempotency?

The biggest risk is copying a pattern without its context. Production systems need clear boundaries, rollback options, tests, and observability before a technique becomes dependable.

How do you test Building Webhooks in PHP: Payload Validation, Retries & Idempotency?

Test the smallest unit that owns the behavior, then add integration coverage for the path users or systems actually rely on. Include failure cases, configuration differences, and regression checks.

How does Building Webhooks in PHP: Payload Validation, Retries & Idempotency affect SEO and AI search visibility?

It improves visibility when the article gives a direct answer, expert context, structured headings, internal links, trustworthy references, and FAQ content that matches the visible page.

Conclusion

Building Webhooks in PHP: Payload Validation, Retries & Idempotency is worth doing when the implementation improves clarity, reliability, or delivery speed. It is not worth doing when it hides ownership, increases operational risk, or makes the system harder to explain.

Use the framework above as a review checklist. Then connect this topic to the rest of the project documentation so readers can move from concept to implementation without losing context.