Webhooks - PlatformDTC

Your app receives platform events at its webhook_endpoint_url, signed with your app’s client_secret. Delivery runs on the same signed, retrying pipeline as Agent Gateway webhooks — the difference is that app webhooks are keyed by your client secret, so you already hold everything needed to verify them.

Subscribing

You do not call a subscribe endpoint. Declare the topics you want on an app version’s webhook_topics, and set the delivery target as your app’s webhook_endpoint_url. When a merchant installs an approved version, the platform auto-registers those topics for that install and delivers to your endpoint.

# On the version you submit for review:
"webhook_topics": ["app/installed", "app/uninstalled", "orders/create"]

To change your endpoint or topics, ship a new version — the change applies to installs of that version, including installs that move to it on approval because it asks for no new required scope.

Delivery format

Each event is a POST to your endpoint with a signature header and a JSON envelope:

POST /hooks/platformdtc
X-Webhook-Event: app/installed
X-Webhook-Id: <subscription id>
X-Webhook-Signature: sha256=<hex hmac>
Content-Type: application/json

{ "event": "app/installed", "data": { … }, "webhook_id": "…" }

Verify the signature

The signature is HMAC-SHA256(client_secret, raw_body), hex-encoded and prefixed sha256=. Compute it over the raw request bytes — not a re-serialized object — and compare in constant time.

import hmac, hashlib

def verify(client_secret: str, raw_body: bytes, header: str) -> bool:
    expected = "sha256=" + hmac.new(
        client_secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, header or "")

import crypto from "node:crypto";

export function verify(clientSecret, rawBody, header) {
  const expected =
    "sha256=" + crypto.createHmac("sha256", clientSecret).update(rawBody).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(header || "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Your endpoint must return 401 on an invalid signature and 200 on a valid one. This is probed during review: the platform sends a request with a deliberately wrong HMAC and expects a 401. An endpoint that accepts unsigned or mis-signed payloads fails review.

During the 72-hour secret-rotation grace, signatures may be produced with either the new or the previous secret. If you have just rotated, accept a body that verifies against either secret until you have fully cut over.

Retries

A delivery is considered successful on a 2xx. Any network error or a >= 400 response is retried — up to 5 attempts with exponential backoff. Make your handler idempotent: de-duplicate on webhook_id, since a retry re-delivers the same event.

App lifecycle topics

Topic	Fires when
`app/installed`	A merchant completes the OAuth install of your app.
`app/uninstalled`	An install is removed; the token is already revoked when this arrives.
`app/scopes_update`	An install’s granted scopes change: a merchant re-consents to a new version, or an approved version drops scopes the install held.

Commerce topics

App versions may also subscribe to store-resource topics to react to merchant activity. Common ones:

Topic	Fires when
`orders/create` · `orders/paid` · `orders/cancelled`	Order lifecycle.
`products/create` · `products/update` · `products/delete`	Catalog changes.
`customers/create` · `customers/update`	Customer records change.
`fulfillments/create` · `fulfillments/update`	Fulfillment progress.
`refunds/create` · `disputes/create`	Money movement.

See the webhook reference for the full topic catalog. Only topics your app actually needs should appear on a version — unused subscriptions are noise the review team will question.

Order payloads

orders/create is sent when checkout completes an order, on every payment method, to each app installed on that store that subscribes to the topic. Each entry in line_items carries the line’s line item properties as app_properties:

{
  "event": "orders/create",
  "data": {
    "order_id": "…",
    "store_id": "…",
    "merchant_id": "…",
    "install_id": "…",
    "line_items": [
      {
        "…": "…",
        "app_properties": {
          "customizer-studio": {
            "properties": [{ "label": "Name", "value": "Alex" }],
            "previewImage": "https://cdn.example.com/previews/a3f9c1.png",
            "_selections": { "name": "Alex" }
          }
        }
      }
    ]
  },
  "webhook_id": "…"
}

install_id is the install that received the delivery (the same id as app/uninstalled, the compliance topics and the session token’s sid), so an order from a store your app has not seen yet can still be attributed to the right install. app_properties is {} for a line without any. Entries arrive exactly as the cart API saved them, private _ keys included. Read the entry under your own app handle.

Compliance payloads

The GDPR compliance topics (customers/data_request, customers/redact, shop/redact) use the same envelope and signature as every other webhook. Public apps must declare all three. Every compliance payload names the install it is for:

Field	Meaning
`install_id`	The install. The same id as `install_id` from the token exchange, `sid` in session tokens and `install_id` in `app/uninstalled`.
`app_id`	Your app.
`store_id` / `shop_id`	The store. Both are `null` for a merchant-wide install, so match on `install_id`.
`shop_domain`	The store’s domain, or `null` when there is none.

shop/redact is sent 48 hours after an uninstall, and is not sent when the app was reinstalled in that window. Delete everything you hold for the install:

{
  "event": "shop/redact",
  "data": {
    "install_id": "0f3c9a1e5b7d4c2a8e6f1b3d5a7c9e0f",
    "app_id": "4b2e8d6c1a3f5e7b9d0c2a4e6f8b1d3c",
    "store_id": null,
    "shop_id": null,
    "shop_domain": null
  },
  "webhook_id": "…"
}

customers/redact is sent when a merchant deletes a customer, to apps holding a customer or order scope (customers:*, orders:*, draft orders, returns or checkout). Delete that customer’s data and the listed orders’ personal data:

{
  "event": "customers/redact",
  "data": {
    "install_id": "…", "app_id": "…", "store_id": "…", "shop_id": "…", "shop_domain": "shop.example.com",
    "customer": { "id": "…", "email": "[email protected]", "phone": null },
    "orders_to_redact": ["…"]
  },
  "webhook_id": "…"
}

customers/data_request is sent when a merchant uses Request customer data on a customer’s page (a customer asked what personal data the store holds), to the same apps. Send the data you hold about that customer to the merchant (by email to the store’s contact address, or in your app’s UI). It carries the same fields as customers/redact, with orders_requested in place of orders_to_redact and data_request: { "id": "…" }:

{
  "event": "customers/data_request",
  "data": {
    "install_id": "…", "app_id": "…", "store_id": "…", "shop_id": "…", "shop_domain": "shop.example.com",
    "customer": { "id": "…", "email": "[email protected]", "phone": null },
    "orders_requested": ["…"],
    "data_request": { "id": "9d1c…" }
  },
  "webhook_id": "…"
}

Answering compliance webhooks

Verify the signature first. Answer 401 when it does not match (review sends a request signed with the wrong secret and expects 401).
Answer 2xx as soon as you have accepted the request, then do the work. Finish it within 30 days.
A topic can go to its own URL: set compliance_webhook_urls on the app (dtc app config). A topic without one goes to your webhook endpoint.
Failed deliveries are retried with backoff (1 minute, doubling, up to 6 hours between tries) for about three days. data_request.id and install_id stay the same on every retry, so use them to de-duplicate.

​Subscribing

​Delivery format

​Verify the signature

​Retries

​App lifecycle topics

​Commerce topics

​Order payloads

​Compliance payloads

​Answering compliance webhooks

Subscribing

Delivery format

Verify the signature

Retries

App lifecycle topics

Commerce topics

Order payloads

Compliance payloads

Answering compliance webhooks