Skip to content
Web Development14 min read

Ecommerce Webhooks: How to Receive Platform Events Reliably

How to handle ecommerce webhooks: architecture, event delivery, signature verification, retries, idempotency, duplicate and out-of-order events, failures and monitoring.

01

Quick answer

To handle ecommerce webhooks reliably, run a small endpoint that verifies the signature using the raw request body, stores or enqueues the event and responds within seconds, then process events asynchronously from a queue. Expect duplicates and out-of-order delivery: deduplicate by event ID, make processing idempotent and use timestamps or fetch current state before acting. Platforms retry failed deliveries for limited periods, so add reconciliation jobs to catch missed events, and monitor volumes, failures and lag. For webhook workflows beyond ecommerce, such as payments, contracts, bookings and alerts, see 12 practical webhook use cases.

02

Where This Fits

Webhooks are one entry point into an event-driven architecture. Processing usually happens through queues. Integration patterns more broadly are covered in API integration.

03

Webhook Architecture

ComponentResponsibility
Receiver endpointVerify signature, persist or enqueue, respond fast
QueueBuffer events, enable retries and parallel processing
WorkersProcess events idempotently, call downstream systems
Deduplication storeRecord processed event IDs
Dead-letter queueHold events that keep failing, with alerts
Reconciliation jobCompare with platform API to catch missed events
04

Signature Verification

Verify every request before trusting it. Compute an HMAC of the raw request body with the shared secret and compare it to the signature header using a constant-time comparison. Use the raw bytes, not a re-serialized JSON object, or verification will fail. Some providers, such as Stripe, include a timestamp in the signature to help reject replayed requests.

Example: verifying an HMAC-SHA256 webhook signature (TypeScript on Node.js)
import crypto from "node:crypto";

export function isValid(rawBody: Buffer, header: string, secret: string) {
  const digest = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("base64");
  const a = Buffer.from(digest);
  const b = Buffer.from(header ?? "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}
05

Respond Fast, Process Later

Platforms expect a quick success response. If your endpoint calls the ERP, sends emails and updates inventory before responding, it will time out under load and trigger retries, causing duplicates. Acknowledge after verification and persistence, and let workers do the rest.

Losing or duplicating orders from webhooks?

ZSpace Labs can rebuild your webhook handling with verification, queues, idempotency and reconciliation, and add the monitoring to prove it works.

Start a Project
06

Retries and Delivery Guarantees

Most platforms provide at-least-once delivery with retries for a limited period. Shopify, for example, retries failed deliveries several times over hours, and Stripe retries for up to three days in live mode, disabling endpoints that keep failing. After that, events can be lost, so your design must include reconciliation. Check each provider's current documentation for exact policies.

07

Idempotency and Duplicates

  • Store processed event IDs (for example Shopify's webhook or event ID headers, Stripe's event ID)
  • Skip events already processed
  • Use idempotency keys when calling downstream APIs
  • Design updates as 'set state to X' rather than 'add X' where possible
  • Keep the deduplication record at least as long as the retry window
08

Out-of-Order Events

An 'order updated' event can arrive before 'order created', and an older update can follow a newer one. Compare timestamps or versions and ignore stale updates, or treat the webhook as a signal and fetch the current state from the API before acting. For sequences that must be processed in order per entity, queue by entity key.

09

Failures

FailureHandling
Invalid signatureReject with 401, log and alert on spikes
Downstream system unavailableRetry from queue with backoff
Bad data in payloadDead-letter with details for investigation
Endpoint outagePlatform retries; reconciliation catches the rest
Endpoint disabled by providerAlert, fix, re-enable and backfill
10

Reconciliation

Schedule jobs that fetch recent orders, payments or products from the platform API and compare them with your records. Process anything missing through the same idempotent workers. Reconciliation turns webhook gaps from silent data loss into a short delay.

11

Security and Secrets

Store secrets in a secrets manager, use different secrets per environment, never log secrets or full sensitive payloads, restrict the endpoint to required methods and sizes, and rotate secrets as providers require.

12

Monitoring

  • Deliveries received by type and source
  • Signature failures
  • Queue depth and processing latency
  • Processing errors and dead-letter count
  • Unexpected silence (no orders webhooks during trading hours)
  • Reconciliation differences
13

Worked Example

An illustrative scenario, not a client case: a brand's order sync processes Shopify order webhooks synchronously, calling the ERP before responding. During a flash sale, the ERP slows, responses time out, the platform retries and some orders are created twice in the ERP. The team changes the endpoint to verify, enqueue and respond immediately, adds deduplication by webhook ID and an idempotency key on ERP calls, and runs an hourly reconciliation against the orders API.

14

Implementation Steps

  • Build a minimal receiver: verify, persist, acknowledge
  • Queue events and process with idempotent workers
  • Store processed event IDs
  • Handle out-of-order updates
  • Add reconciliation against the platform API
  • Monitor volumes, failures, lag and silence
15

Common Mistakes

  • Processing synchronously before responding
  • Verifying signatures against parsed JSON
  • No deduplication
  • Assuming in-order delivery
  • No reconciliation
  • Logging secrets or full customer payloads

Ready to make webhook integrations dependable?

Talk to ZSpace Labs about integration engineering, Shopify app and webhook development and event-driven automation.

Start a Project
16

Conclusion

Reliable webhooks come down to verify, persist, acknowledge, process idempotently, handle order, reconcile and monitor. Related: event-driven architecture and queue architecture.

FAQ

Common questions.

An HTTP request a platform sends to your endpoint when something happens, such as an order being created, a payment succeeding or a product being updated, so your systems can react without polling.

Quickly. Verify the signature, store or enqueue the event and return a success status, then process asynchronously. Slow endpoints cause timeouts and retries.

To confirm the request came from the platform and was not altered. Platforms sign payloads with a shared secret, for example Shopify's X-Shopify-Hmac-SHA256 header or Stripe's Stripe-Signature header.

Yes, with different policies. Shopify retries failed deliveries several times over a few hours; Stripe retries for up to three days in live mode. Check each platform's documentation and alerting for disabled endpoints.

Yes. Retries, network issues and platform behaviour cause duplicates. Store processed event IDs and skip repeats, and make processing idempotent.

Not guaranteed. An update can arrive before the create, or an older update after a newer one. Use timestamps or versions, or fetch the latest state from the API before acting.

The platform retries for a period, then may stop. You can miss events. Run periodic reconciliation that compares your data with the platform API to catch gaps.

Platforms vary. Even with full payloads, consider fetching the current state from the API for critical actions, because the payload may be out of date by the time you process it.

Store them in a secrets manager, rotate them when required, never log them, and use different secrets per environment.

Track deliveries received by type, verification failures, processing errors, queue depth, processing latency and reconciliation differences, with alerts for spikes or silence.

Get in touch

Have a project in mind?

Whether you're building a new digital product, improving an existing website, or looking to automate part of your business — let's talk.