POST
Register a webhook endpoint

Authorizations

Authorization
string
header
required

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

Idempotency-Key
string
required

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

application/json

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.

url
string
required

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.

subscribed_events
enum<string>[]
required

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/created requires read_customers
  • customers/deleted requires read_customers
  • customers/updated requires read_customers
  • fulfillments/created requires read_fulfillment
  • fulfillments/updated requires read_fulfillment
  • inventory/updated requires read_inventory
  • orders/cancelled requires read_orders
  • orders/fulfilled requires read_orders
  • orders/paid requires read_orders
  • orders/refunded requires read_orders
  • products/created requires read_products
  • products/deleted requires read_products
  • products/updated requires read_products
  • reviews/created requires read_reviews
  • reviews/updated requires read_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.

Available options:
*,
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

data
object