Skip to main content
POST
Register an HTTPS endpoint to receive real-time product event notifications. See Event subscription notification for the delivered payload, signature verification, and retry behavior. The response includes a one-time signingSecret used to verify the X-Headout-Signature header on delivered events — store it immediately, it cannot be retrieved again. Use Rotate signing secret if you lose it. authentication.value is sent verbatim as the Authorization header on every delivery attempt, including retries. It must be 6–1024 characters with no control characters, and is never returned by a read — only a masked authentication.valueHint. Subscriptions are created active and start receiving events immediately. Pass "active": false to create one paused, then enable it with Update event subscription.

​
Error responses

Errors on the event subscription endpoints use the same envelope as the rest of the Partner API. The HTTP status tells you the class of failure; error.code is the stable, machine-readable value to branch on.
message wording is not part of the contract and may be reworded without notice. Treat error.code as the only stable signal.

Authorizations

​
Headout-Auth
string
header
required

Body

application/json
​
url
string<uri>
required

HTTPS URL Headout will deliver events to. Must be a valid absolute URL with no embedded credentials.

Pattern: ^https://.*
​
eventTypes
enum<string>[]
required

One or more event types to subscribe to. Must be non-empty with no duplicates.

Minimum array length: 1

The event types available for subscription:

  • product.listing_status_changed — A product was listed or unlisted.
  • product.variant_listing_status_changed — One or more variants under a product were listed or unlisted. Fires when a product is listed (its variants arrive as listed) or delisted (all its variants are reported delisted), and also while a product stays listed but individual variants under it are listed or delisted.
  • product.data_changed — The content of a product that is listed (and was listed at the previous sync) changed. data.changedFields names which fields differ. Listing/unlisting and variant add/remove are reported by the two events above, not here.
  • product.variant_pricing_changed — The near-term pricing of a variant under a listed product changed for a specific date. data names the productId, variantId, and date whose price moved, not the new amounts — re-fetch the price to read them.
Available options:
product.listing_status_changed,
product.variant_listing_status_changed,
product.data_changed,
product.variant_pricing_changed
​
authentication
object

Authentication Headout attaches to webhook deliveries for this subscription. Tri-state on update: omit this field entirely to keep the current authentication unchanged, send {"type": "NONE"} to clear it, or send {"type": "AUTHORIZATION_HEADER", "value": "..."} to set it.

​
description
string

Optional free-text label to help you identify this subscription.

Maximum string length: 500
​
active
boolean
default:true

Whether the subscription should start delivering events immediately. Defaults to true. Set false to create it paused and enable it later with Update event subscription.

Response

Event subscription created. The signingSecret is only ever returned here and from Rotate signing secret — store it now, it cannot be retrieved again.

​
id
string

Identifier of this subscription, e.g. whsub_01j.... Use in Get/Update/Delete/Rotate secret.

​
url
string

HTTPS URL events are delivered to.

​
eventTypes
enum<string>[]

Event types this subscription is subscribed to.

The event types available for subscription:

  • product.listing_status_changed — A product was listed or unlisted.
  • product.variant_listing_status_changed — One or more variants under a product were listed or unlisted. Fires when a product is listed (its variants arrive as listed) or delisted (all its variants are reported delisted), and also while a product stays listed but individual variants under it are listed or delisted.
  • product.data_changed — The content of a product that is listed (and was listed at the previous sync) changed. data.changedFields names which fields differ. Listing/unlisting and variant add/remove are reported by the two events above, not here.
  • product.variant_pricing_changed — The near-term pricing of a variant under a listed product changed for a specific date. data names the productId, variantId, and date whose price moved, not the new amounts — re-fetch the price to read them.
Available options:
product.listing_status_changed,
product.variant_listing_status_changed,
product.data_changed,
product.variant_pricing_changed
​
description
string | null

Free-text label for this subscription, if set.

​
active
boolean

Whether this subscription is currently active.

​
createdAt
string<date-time>

When this subscription was created.

​
updatedAt
string<date-time>

When this subscription was last updated.

​
authentication
object
​
signingSecret
string | null

Signing secret for this subscription, used to verify the X-Headout-Signature header on delivered events. Only present in the response to Create event subscription and Rotate signing secret — never returned again afterwards, so store it immediately.

​
signingSecretHint
string | null

Masked trailing characters of the current signing secret, returned on reads so you can tell which secret is active without exposing it.