Register a webhook endpoint
Registers an endpoint and returns its signing secret. TWO GRANTS ARE CHECKED, not one. write_webhooks reaches this route; every entry in subscribed_events is then checked against its own family’s read scope, so an endpoint receiving orders/paid also needs read_orders, and the 403 names the scope that is missing. The WebhookTopic schema lists every subscribable topic with the scope it costs.
Authorizations
A secret API key. Publishable keys cannot reach this API. A key may carry an expiry, and an expired key is refused exactly like an unknown one, with a 401 that names no reason; check the key's expires_at in the dashboard rather than inferring it from a response. When a merchant rolls a key's secret they choose a grace window of up to 3 days, and for its duration BOTH the new secret and the one it replaced authenticate, so an integration moves over on its own deploy schedule instead of at the instant the button is pressed. Move before the window closes: after it, the old secret is refused. Nothing else about this contract moves with a roll. The key keeps its id and its scopes, so the only thing an integration updates is the credential itself.
Headers
A unique key per logical write. Replaying a request with the same key returns the first response byte for byte instead of applying the write twice.
Body
THE RESPONSE CARRIES THE SIGNING SECRET AND NOTHING ELSE EVER WILL. Store it before doing anything else: no read returns it, and the only way back is POST /api/v1/webhook-endpoints/{webhookEndpointId}/rotate-secret, which issues a new one rather than showing this one again.
Where deliveries are sent. Must be an https address on the public internet; private, loopback and link-local addresses are refused, since an endpoint pointing inside the platform's own network would make this API a request forwarder.
The event types this endpoint receives, at least one. Spelled subscribed_events in both directions, matching the field it is served back under. An unregistered type is refused HERE rather than accepted and never delivered, so a typo is a 400 instead of a receiver that silently never fires.
An event type an endpoint can subscribe to.
SUBSCRIBING COSTS TWO GRANTS. write_webhooks reaches the endpoint
routes themselves; each topic is then checked against its own
family's read scope, so an endpoint receiving orders/paid needs
read_orders as well. The 403 names the scope that is missing.
customers/createdrequiresread_customerscustomers/deletedrequiresread_customerscustomers/updatedrequiresread_customersfulfillments/createdrequiresread_fulfillmentfulfillments/updatedrequiresread_fulfillmentinventory/updatedrequiresread_inventoryorders/cancelledrequiresread_ordersorders/fulfilledrequiresread_ordersorders/paidrequiresread_ordersorders/refundedrequiresread_ordersproducts/createdrequiresread_productsproducts/deletedrequiresread_productsproducts/updatedrequiresread_productsreviews/createdrequiresread_reviewsreviews/updatedrequiresread_reviews
* subscribes to every topic listed above, including ones added
after you subscribe, and therefore requires every read scope named
here rather than the ones your key happens to hold.
A few events the platform dispatches internally sit outside this taxonomy and cannot be subscribed to with an API key. They are absent from this list rather than refused after you send them.
*, customers/created, customers/deleted, customers/updated, fulfillments/created, fulfillments/updated, inventory/updated, orders/cancelled, orders/fulfilled, orders/paid, orders/refunded, products/created, products/deleted, products/updated, reviews/created, reviews/updated Response
Created
