Skip to content
Tutorials Center
My learning

Topics

Lesson 41 of 55 ยท Compliance, Security, Review

Privacy, GDPR and Mandatory Webhooks

Handle Shopify's mandatory privacy webhooks: customer data request, customer redact and shop redact. Includes uninstall cleanup and a runnable redaction handler.

Your app stores data about people: customers, their addresses, their orders. Laws such as the GDPR in Europe and the CCPA in California give those people rights over that data, including the right to see it and the right to have it erased. The merchant is responsible to the customer, but your app holds a copy, so Shopify passes those requests on to you through three mandatory privacy webhooks. An app that does not handle them cannot be listed on the App Store, and handling them badly is a legal problem for your merchants and for you.

This lesson explains the three webhooks, what a correct handler does, how uninstalling relates to them, and how to keep as little personal data as possible in the first place. The platform configuration and route code are read-only here. The runnable examples are plain-JavaScript stand-ins for a verified compliance endpoint and a redaction routine, using made-up data. They are an engineering illustration, not legal advice: ask a lawyer what your obligations are in your market.

The three mandatory topics

Topic When Shopify sends it What you must do
customers/data_request A customer asks the merchant for the data stored about them Collect the personal data your app holds for that customer and give it to the merchant
customers/redact A customer asks the merchant to delete their data (Shopify waits a while first, for example if recent orders must be kept) Erase or anonymize that customer's personal data in your systems
shop/redact About 48 hours after a merchant uninstalls your app Erase everything you hold for that shop

Shopify sends these to the subscription you configured, signed in the same way as other webhooks. Timings and retention rules are set by Shopify and can change, and Shopify states a deadline (currently 30 days) for completing the work after you receive a request. Always read the current platform documentation before you ship.

The payloads are small. Here is an abridged customers/redact body (all values are invented):

JSON
{
  "shop_id": 954889,
  "shop_domain": "example-shop.myshopify.com",
  "customer": { "id": 191167, "email": "[email protected]", "phone": "+15555550100" },
  "orders_to_redact": [299938, 280263]
}

A customers/data_request body looks similar and adds orders_requested and a data_request object with an id. Your handler uses the shop domain to find the right tenant, and the customer id (or email) to find the right rows.

flowchart TD
    C["Customer asks the<br/>merchant"] --> S["Shopify"]
    S -->|"customers/data_request"| H["Your compliance<br/>endpoint"]
    S -->|"customers/redact"| H
    U["Merchant uninstalls"] --> S
    S -->|"shop/redact<br/>after about 48 hours"| H
    H --> V{"Valid<br/>signature?"}
    V -->|"no"| R401["401"]
    V -->|"yes"| Q["Queue the job,<br/>reply 200"]
    Q --> W["Worker exports or<br/>erases the data"]

One endpoint receives all three topics, verifies them, and hands the real work to a worker.

Subscribing in the app configuration

The mandatory topics are declared in shopify.app.toml as compliance topics, usually pointing at one route. This is real configuration, read-only here; check App Configuration with shopify.app.toml for the surrounding file and confirm the key names against the current CLI version.

TOML
# shopify.app.toml (read-only excerpt)
[webhooks]
api_version = "2026-01"

  [[webhooks.subscriptions]]
  compliance_topics = [ "customers/data_request", "customers/redact", "shop/redact" ]
  uri = "/webhooks/compliance"

Run shopify app deploy to make the subscription live; the configuration becomes part of an app version. The app template ships with route files for these topics so you can see where your code goes.

What a correct handler does

Every mandatory endpoint follows the same recipe:

  1. Verify the signature against the raw body. A forged shop/redact could otherwise delete a real merchant's data. This is the same check as in Verifying Webhook Signatures; if it fails, answer 401.
  2. Respond with 200 quickly, then do the work. An export or a cascade of deletes may take longer than the delivery timeout. Queue a job, as in Reliable Webhook Handlers.
  3. Be idempotent. The same request can arrive twice. Erasing something that is already gone must succeed quietly.
  4. Scope by shop. Always filter by the shop domain from the payload, so one merchant's request never touches another's data. This is the multi-tenant rule from Databases and Session Storage in Production.
  5. Leave an audit trail that records that a request was processed (topic, shop, time, result) without keeping the personal data you just deleted.

The first stand-in below combines the first, second and fourth steps: it verifies a signature, routes by topic and queues a job.

Node.js A verified compliance endpoint (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Only the genuine request ends up in the queue. The forged one is rejected before any parsing, which is the property that matters most.

Redacting without breaking your books

"Delete everything about the customer" collides with another need: you may have to keep some records, for example invoices for tax or accounting. The usual resolution is anonymization: keep the order row and its amounts, but overwrite every field that identifies a person. What you must keep, and for how long, depends on law and on the merchant's own obligations; the general ideas are in Privacy and Compliance.

A practical redaction routine:

  • Delete rows that exist only to describe a person: saved preferences, notes, marketing profiles.
  • For rows you must keep, replace personal fields with fixed placeholders and keep numbers, dates and ids.
  • Remove the same data from every place it lives: the main database, search indexes, caches, analytics tables, logs you control and backups that are restored (or rely on backup expiry and document it).
  • Never log the personal data you are processing, including in the audit record.
JS Redact a customer, keep the accounting

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Three properties to notice. The retry returns deleted: 0 and changes nothing, so it is idempotent. The other shop's Ada is not touched, because every query includes the shop. And the audit trail has counts but no names or emails.

Uninstall cleanup versus shop/redact

These two events are easy to confuse.

  • app/uninstalled arrives immediately. Use it to stop work: delete the stored access token and session so you cannot call the shop's API any more, cancel scheduled jobs and mark the shop inactive. Do not delete business data yet: a merchant may reinstall within hours and expect their settings back.
  • shop/redact arrives about 48 hours later, when it is clear the merchant is not coming back. Now delete everything for that shop.

If the same shop reinstalls before the redact arrives, treat it as a new, empty tenant after the redact has run, and make sure your worker does not delete the new installation's data by mistake (compare the install time against the request time).

Data minimization

The cheapest personal data to protect is the data you never stored. Before saving a field, ask whether a feature really needs it.

  • Request only the access scopes you need (Managed Installation and Access Scopes); apps that read orders or customers also have to apply for access to protected customer data, as covered in Orders, Customers and Protected Data. Shopify reviews the stated reason.
  • Store ids and fetch details on demand instead of copying names and addresses.
  • Encrypt sensitive fields at rest, restrict who on your team can read production data, and set retention periods so old rows are deleted automatically.
  • Publish a privacy policy that matches what the app really does; the listing review checks that you have one.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which webhook tells you to erase everything you hold for a shop?

    shop/redact arrives about 48 hours after an uninstall and means all data for that shop should be erased. app/uninstalled only signals that the app was removed.
  2. 2. A customers/redact request arrives with an invalid HMAC signature. What should the endpoint do?

    An unsigned or forged request could make you delete real data. Verify first and reject with 401 if the signature does not match.
  3. 3. You must keep invoices for tax reasons, but a customer asked for erasure. What is a common approach?

    Anonymization keeps the accounting facts and removes personal identifiers. Check with legal advice what you must keep and for how long.
  4. 4. What should the app/uninstalled handler do, compared with shop/redact?

    On uninstall you revoke access and stop jobs, but keep data for a possible quick reinstall. The permanent deletion is triggered later by shop/redact.
  5. 5. Why must every database query in a redaction job include the shop domain?

    Your database is multi-tenant. Without the shop filter, a request for one merchant could erase or export another merchant's records.

Summary

  • Apps must handle three mandatory webhooks: customers/data_request, customers/redact and shop/redact, declared as compliance topics in the app configuration.
  • Verify the signature, answer quickly, queue the work, and make every job idempotent and scoped by shop.
  • Export data for requests, and erase or anonymize it for redactions across every store of it, keeping only what the law lets you or requires you to keep.
  • On app/uninstalled, revoke tokens and stop jobs; on shop/redact, delete the shop's data.
  • Store less personal data to begin with, and write the facts of processing to an audit trail without the personal data itself.

Next: App Security Checklist