E-commerce Webhooks: How Payments and Shipping Communicate with Your Store

Webhook, API, and polling compared

Example: payment succeeds after the browser closes

Your store creates a payment attempt and directs the customer to the provider interface. The customer may complete payment without returning. A server notification lets the store match the transaction and update the order without the browser.

A frontend success message must not independently mark an order paid. Use a trusted provider result as evidence, while the success page communicates the current state to the customer.

A reliable ingestion architecture

A proposed flow is provider, HTTPS endpoint, verification, durable inbox, receipt acknowledgment, queue, and worker. This is an architectural recommendation, not a universal provider protocol.

Avoid sending email, creating shipments, or waiting for a CRM within ingestion if those actions delay the response. Persist and acknowledge the event, then process it in the background. HTTP success means you accepted responsibility, not that every effect has finished.

Source: Azure: queue-based load leveling

Verify authenticity before trusting the payload

Verification mechanisms differ: a signature over the raw body, an HMAC over selected fields, or another server-side procedure. Implement the provider's documented algorithm instead of borrowing another company's recipe.

Stripe signature verification requires the raw request body; modifying it first can invalidate verification. Keep test and production secrets separate, and review replay protection and secret rotation for the specific integration.

Source: Stripe: webhook signatures

A valid signature is not the whole business check

• Match the merchant account and test or production environment.
• Link the transaction reference to an existing payment attempt and the correct order.
• Validate amount, currency, event type, and current state.
• Reject invalid transitions, such as moving paid back to pending because of an old event.
• Do not let arbitrary payload fields trigger operations outside the integration's scope.

Deduplicate both events and side effects

Events may arrive more than once. Use a unique provider-and-event identifier and record processing status. Avoid a check-then-insert approach without a uniqueness constraint, which races under concurrent deliveries.

Inbox deduplication cannot protect every effect: distinct events may describe the same operation, or a worker may crash after creating a shipment but before recording success. Use stable effect identifiers, appropriate constraints, and supported API idempotency keys.

Avoid the database-to-queue delivery gap

If an event is stored but the process crashes before queue publication, it can remain unprocessed. Use a transactional outbox or a periodic worker that recovers unprocessed inbox records. Choose a design with an explicit recovery path.

Do not acknowledge success before durable persistence. A duplicate already stored can be acknowledged if its processing or recovery path remains intact. Aim for one correct logical effect, not a claim of universally guaranteed exactly-once network delivery.

Events may be delayed or out of order

Do not assume created always arrives before succeeded. State rules should tolerate missing events, with provider queries when current truth is needed. Use event time or resource versions when available rather than treating receipt order as business order.

For shipping, map carrier states to store states such as in_transit, delivered, and delivery_failed. A delivered parcel does not prove completion of every item in a multi-shipment order.

Retries and a dead-letter queue

Define attempt limits, timing, and error classification. A transient outage may be retryable, while an invalid payload or forbidden transition needs review rather than an endless loop.

Move exhausted events into a visible failure queue with an alert, reason, and order correlation. Replays must pass the same safety rules. Response deadlines and retry policies vary by provider; do not assume one schedule fits all.

Simplified ingestion pseudocode

This illustrates operation order, not a production-ready endpoint. Signature verification must implement the provider contract, and inbox and outbox records must share the same transaction.

event = verify_provider_signature(raw_body, headers, secret)
validate_provider_and_environment(event)

with database.transaction():
    inserted = inbox.insert_if_new(
        provider=event.provider,
        event_id=event.id,
        payload=event
    )
    if inserted:
        outbox.add('process_webhook', event.id)

return HTTP_200

# Worker: validate business data, apply safe transitions,
# retry transient failures, and record processing results.

What to test before launch

• Invalid signatures, wrong secrets, and incorrect environments.
• Concurrent duplicate deliveries and distinct events for the same operation.
• Late events after newer confirmations or reservation expiration.
• Database or queue outages and worker crashes midway through processing.
• Payment without a browser return, partial refunds, and delivery exceptions.
• Replaying failed events without duplicate shipments or inventory deductions.

Monitoring and reconciliation complete the integration

Monitor ingestion and processing latency, signature failures, queue depth, oldest event age, retries, and terminal failures. Correlate logs with order and transaction identifiers without exposing secrets or sensitive data.

Periodically reconcile unresolved payments and shipments against the provider API. Webhooks are valuable notifications, not a substitute for detecting outages, checking external truth, and repairing mismatches.