- Lifecycle webhooks can arrive after Shopify revokes merchant sessions or access tokens.
- Verify Shopify webhook HMACs independently before lifecycle cleanup begins.
- Keep uninstall and privacy handlers narrow, resilient, and free of session dependencies.
- Test authentication behavior when merchant credentials are already revoked.
- Use separate controls for signed webhook verification and interactive app sessions.
Shopify app teams need a reliable way to process uninstall and privacy webhooks when a merchant’s active session is no longer available. The practical design decision is straightforward: verify the webhook’s cryptographic signature independently of any authentication flow that depends on a live merchant session.
This matters because lifecycle events can arrive while, or after, Shopify has revoked the merchant credentials your embedded app normally uses. If an uninstall handler begins by requiring a valid merchant session, the application may lose the very event it needs to remove tenant infrastructure and complete its cleanup work.
Why lifecycle webhooks need their own authentication path
Interactive application requests and Shopify lifecycle webhooks serve different purposes. An embedded app request is associated with a user or merchant context. A lifecycle webhook is a signed server-to-server message from Shopify that tells your system about a platform event.
For lifecycle routes, the useful question is whether the incoming request was signed by Shopify. HMAC verification answers that question without requiring the merchant’s current access token or session to remain valid.
Request type | Primary authentication concern | Operational dependency |
|---|---|---|
Embedded app request | Validate the current merchant or user session | A live session and applicable access credentials |
Lifecycle webhook | Validate the webhook HMAC signature | The app’s webhook secret and the received request payload |
Keeping these paths distinct gives lifecycle handlers the ability to run during the conditions that make them necessary. It also makes the intent of each route easier to review and maintain.
What this looks like in a multi-tenant Shopify app
In a recent multi-tenant Shopify application, a shared embedded app supported merchant-specific storefront processes and supporting infrastructure. An uninstall event required tenant deprovisioning work that included removing PM2 processes, nginx configuration, and tenant environment files.
That cleanup path could not safely depend on an active merchant session. The merchant may have removed the app before the webhook arrives, and Shopify may have revoked credentials as part of that lifecycle change.
The implementation introduced a dedicated webhook HMAC authentication module and applied it to these lifecycle routes:
app/uninstalledcustomers/data_requestcustomers/redactshop/redact
The result is a clearer boundary: a verified webhook can enter the lifecycle handler, while ordinary interactive application routes continue using session-aware authentication suited to their purpose.
Design lifecycle handlers for narrow, dependable work
An uninstall or privacy webhook should perform a defined operational task. Broad route behavior increases the chance that unrelated application dependencies interfere with a cleanup or compliance path.
For a multi-tenant application, that usually means identifying the affected tenant, carrying out the required deletion or deprovisioning action, and limiting the handler to resources relevant to that event. The exact work depends on the architecture. It may involve application data, background processes, runtime configuration, files, or external service records.
For Shopify applications with headless storefronts or tenant-specific runtime processes, lifecycle design should be considered during architecture planning. The same operational questions that shape storefront deployment also shape clean removal and reinstall behavior. Teams planning this kind of setup can review Shopify Hydrogen development considerations alongside the broader Shopify application and integration architecture.
A practical implementation sequence
Receive the webhook request. Preserve the request data needed for signature validation.
Run dedicated HMAC verification. Validate that Shopify signed the webhook before lifecycle business logic begins.
Route the verified event to a focused handler. Keep uninstall, data-request, and redaction logic specific to the event.
Use internal tenant records for operational cleanup. Lifecycle work should be able to identify the affected tenant without relying on a newly valid merchant session.
Keep session-aware authentication on interactive routes. Merchant-facing app functionality still has its own authorization requirements.
This separation also improves maintenance. A future change to embedded session handling has less reason to alter the mechanics of privacy and uninstall processing. A future change to lifecycle cleanup has less reason to affect ordinary app navigation.
Test the failure condition, not only the happy path
The important lifecycle scenario is the one where merchant credentials have already been revoked. A test plan should confirm that the HMAC authentication layer accepts valid Shopify-signed webhooks without requiring a live merchant session.
The referenced implementation included unit coverage for webhook HMAC authentication. That is a useful baseline because signature validation is the gate that protects these routes from unverified requests.
Teams should also review the expected behavior for invalid signatures, altered payloads, missing headers, and events associated with tenants that have already been removed. Those cases help ensure the handler remains safe when platform events arrive near the end of a merchant relationship.
How we know
This article is based on implementation work in a multi-tenant Shopify application with a shared embedded app, merchant-specific storefront processes, OAuth, billing, POS extensions, and server-to-server APIs. The documented change added a dedicated webhook HMAC authentication module, moved uninstall and Shopify privacy routes onto that authentication path, and included unit tests for the HMAC behavior.
The source material specifically identifies the operational risk: Shopify lifecycle webhooks may arrive after merchant sessions or access tokens have been revoked. It also documents tenant deprovisioning work associated with uninstall handling.
Limits
This pattern addresses authentication for Shopify lifecycle webhooks. It does not define every authorization decision inside an application, nor does it replace the session handling needed for interactive merchant and user workflows.
The available implementation evidence documents the architectural change and unit coverage. It does not include measured delivery times, incident rates, cost savings, or business-performance outcomes. Those results depend on the application architecture, the completeness of its cleanup logic, and the operational controls around it.
Review lifecycle paths before they become an incident
If your Shopify app provisions tenant-specific services, configuration, or storefront runtime resources, map the uninstall and privacy paths alongside the installation flow. Confirm which routes depend on a merchant session, which events require independent HMAC verification, and which resources must be removed or redacted.
For teams working through those decisions, ecommerce development planning and application support planning can provide a useful starting point for reviewing lifecycle behavior, webhook handling, and production operations.