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.

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`	A merchant re-consents to a new version, changing the granted scopes.

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.

GDPR compliance topics (customers/data_request, customers/redact, shop/redact) are mandatory for public-marketplace apps in a later phase. Custom-distribution api apps can subscribe now if they handle customer PII.

​Subscribing

​Delivery format

​Verify the signature

​Retries

​App lifecycle topics

​Commerce topics

Subscribing

Delivery format

Verify the signature

Retries

App lifecycle topics

Commerce topics