A webhook is not reliable simply because an endpoint returned a successful response once. Real delivery includes duplicate events, delays, reordered messages, expired secrets, network timeouts, provider retries, and receivers that fail after partially applying an update.
A dependable integration must authenticate each message, accept it durably, process it safely, and prevent duplicate effects. These behaviours should be tested on staging and included in the release process.
This guide is for WordPress product owners, developers, and agencies that need a repeatable engineering decision.
Verify the Raw Request Before Parsing
Webhook authentication should begin with the exact raw request body received by the endpoint.
Use the provider’s documented signature algorithm, a securely stored signing secret, and the required header format. Do not decode JSON, normalize whitespace, or rebuild the payload before verification. Small formatting changes can produce a different digest.
Use a constant-time comparison for signatures. Reject unsupported algorithms, missing headers, malformed values, and mismatches.
Never create a “close enough” version of a provider’s protocol. Follow the documented algorithm exactly, and do not log the signing secret, authorization headers, or complete payload during debugging.
Prevent Replay Attacks
A valid signature proves that the message was created by someone with the signing secret. It does not always prove that the request is recent.
When the provider includes a timestamp, nonce, or replay-protection value, validate it before accepting the event. Define an allowed time window that permits reasonable delivery delays without allowing captured requests to be replayed indefinitely.
Reject timestamps that are too old, too far in the future, or incorrectly formatted. Replay protection complements idempotency because the same valid event may arrive twice within the accepted window.
Apply Limits Before Expensive Processing
A valid signature does not make every payload safe to process synchronously.
Set a maximum body size before decoding or database work. Apply rate limits to protect the endpoint from bursts and accidental loops.
Validate the content type and basic envelope. Reject oversized, malformed, or incomplete payloads to protect memory and database capacity.
Acknowledge Quickly and Process Separately
The receiving endpoint should perform only the work required for durable acceptance.
Authenticate the message, validate the envelope, persist the event, enqueue processing, and respond within the provider’s timeout. Avoid slow external API calls, report generation, multiple emails, or large order updates before acknowledging the request.
Business processing belongs in a background job. This reduces needless redelivery and prevents temporary downstream failures from blocking the endpoint.
The WordPress REST API can receive the event, while Action Scheduler or another controlled queue applies the business effect. Follow the provider contract when choosing the response status. In many integrations, success means the event was accepted durably, not that every downstream action is complete.
Persist Before Acknowledging
Do not return success until the event has been stored in a way that survives process termination.
If the endpoint responds first and PHP fails before persistence, the provider may believe delivery succeeded even though the event was lost.
Store the event ID, type, received time, verification result, state, attempt count, and a minimal sanitized payload or reference. Distinguish accepted, queued, processing, completed, retrying, and failed states.
Use a transaction when several database writes must succeed together.
Use Event IDs for Idempotency
Providers may send the same event more than once. A timeout, dropped response, or internal retry can create duplicates even when the first request succeeded.
Store the provider event ID under a unique database constraint. If the event already completed, return success without applying it again. If it is processing, avoid starting a concurrent worker.
A unique constraint is stronger than checking first and inserting later because concurrent requests may pass an application-level check.
When no stable event ID is supplied, create a deterministic idempotency key from fields defined by the provider contract.
Make Business Operations Idempotent
Deduplicating the event record is only part of the solution. The business operation must also tolerate retries.
A worker may update an order, send an email, and crash before marking the event complete. A retry could repeat the email even though the order update already happened.
Break complex processing into recorded steps. Before issuing a refund, applying a credit, or sending a notification, check whether that effect already completed.
Use stable idempotency keys when calling payment providers or third-party APIs that support them.
Do Not Assume Chronological Delivery
Webhooks may arrive out of order. A delayed pending event can arrive after a newer completed or cancelled event.
Compare resource versions, sequence numbers, or event timestamps according to the provider contract. Do not allow an older event to overwrite newer state merely because it arrived later.
When ordering guarantees are unclear, retrieve the current resource through the provider API before making a destructive change. Use the WordPress HTTP API for outbound requests with timeouts, response validation, and controlled retries.
Record why an event was ignored as stale so support teams can distinguish correct behaviour from failure.
Design Safe Retry Behaviour
Retries should be bounded and classified.
Temporary failures may justify exponential backoff. Permanent failures such as unsupported event types or revoked authorization should not retry indefinitely.
Set a maximum attempt count and move exhausted events into a failed state that administrators can inspect. Permission-protected manual retry should reuse the same idempotency controls.
Avoid tight retry loops because immediate repeated attempts can increase load during an outage.
Rotate Secrets Safely
Allow a short overlap in which the current and next secrets can verify requests. Record which secret version authenticated the event, but never store the secret in logs.
After the provider has switched and delivery is confirmed, retire the old secret. Test rotation on staging when test events are available.
Log a Delivery Trail Without Leaking Data
Record event type, provider ID, received time, verification result, processing state, attempts, duration, and a sanitized error category.
Keep payload retention minimal. Redact personal data, tokens, cookies, authorization headers, and payment details before storage. Apply automatic expiry and restrict viewing, export, deletion, and retry actions with appropriate capabilities and nonces.
For a custom integration, define these operational behaviours in the plugin brief before development.
Implementation Checklist
Verify signatures against the raw body. Enforce replay windows. Reject malformed headers and unsupported algorithms. Apply rate limits and body-size limits. Persist before acknowledging. Process business work asynchronously. Deduplicate with a unique event ID. Make side effects idempotent. Handle reordered events. Bound retries. Rotate secrets safely. Redact and expire delivery logs.
Acknowledge Quickly and Process Separately
The receiving endpoint should perform only the work required for durable acceptance.
Authenticate the message, validate the envelope, persist the event, enqueue processing, and respond within the provider’s timeout. Avoid slow external API calls, report generation, multiple emails, or large order updates before acknowledging the request.
Business processing belongs in a background job. This reduces needless redelivery and prevents temporary downstream failures from blocking the endpoint.
The WordPress REST API can receive the event, while Action Scheduler or another controlled queue applies the business effect. Follow the provider contract when choosing the response status. In many integrations, success means the event was accepted durably, not that every downstream action is complete.
Build Secure and Reliable WordPress Webhook Integrations
Contact WPStack to strengthen your webhook workflow with raw-request signature verification, replay protection, durable event storage, asynchronous processing, safe retries, secret rotation, and privacy-conscious delivery logs.
WPStack provides custom WordPress plugin development and integration services to help businesses build production-ready webhook systems with idempotent processing, duplicate-event protection, ordered state handling, secure authentication, and reliable background workflows.
Planning a new webhook integration or fixing unreliable event delivery in an existing plugin? Request a custom WordPress plugin assessment with WPStack and discuss your requirements with an experienced development team.
Frequently Asked Questions
Usually no. If the original event completed successfully, acknowledge the duplicate without applying its effect again.
Follow the provider contract. Commonly, the endpoint returns success after durable acceptance while background processing continues.
Support a short overlap where current and next secrets are accepted. Record which version verified the request, confirm provider delivery, and then retire the old secret.
No. Network controls provide defence in depth, but signatures authenticate the message and protect its integrity according to the provider protocol.
Planning a production plugin? Review what makes a WordPress plugin production-ready, browse the WPStack plugin directory, or discuss a custom build.
Aditya Bhimrajka is a technology entrepreneur, product strategist, and software solutions expert with over a decade of experience building scalable web and mobile applications. His expertise spans SaaS, AI, cloud technologies, custom software development, and digital transformation. Passionate about solving real-world business challenges through technology, Aditya shares practical insights on WordPress, plugins, software development, startup growth, product strategy, and emerging technologies. At WPStack, he writes actionable, experience-driven content that helps developers, businesses, and website owners build secure, high-performing, and future-ready WordPress solutions.
