DoctorX logoDoctorX Get an API key

Webhooks

DoctorX posts a signed JSON event to your HTTPS endpoint when something changes.

Register an endpoint

Add an endpoint in the dashboard under Settings → Integrations → Webhooks, where you can also send a test event, rotate its signing secret and replay deliveries; or with a key holding webhooks:manage, through the Webhooks endpoints. The signing secret is shown once, when the endpoint is created or its secret rotated.

Webhooks

Register an HTTPS receiver, then verify every delivery:

expected = "sha256=" + hex(HMAC_SHA256(secret, timestamp + "\n" + rawBody))

Compare it in constant time against X-DoctorX-Signature, and reject a X-DoctorX-Timestamp more than 300 seconds from now (that check is what makes a captured delivery non-replayable). Sign the raw bytes before any JSON parse: re-serialising changes key order and number formatting and the digest will not match.

The body you receive is published as the WebhookEventPayload schema of this document. schemaVersion is bumped only on a breaking change to data, never for an added optional field, so treat unknown fields as additive rather than rejecting them.

X-DoctorX-Event-Id is stable across retries, so de-duplicate on it. Respond 2xx to acknowledge. Anything else, including a redirect (which is not followed), counts as a failure and is retried with exponential backoff up to 6 attempts. After 20 consecutive failures the endpoint is disabled and must be re-enabled explicitly. The events it would have received meanwhile are kept as HELD deliveries for 30 days from the moment it was disabled and are sent, oldest first, once it is re-enabled. Deliveries are retained and replayable for 30 days.

Events

An endpoint registered with an empty events list receives every event, including ones added later; an endpoint with an explicit list receives exactly those. GET /webhooks/events serves this catalog at runtime.

EventFires when
shop.connectedA marketplace shop finished authorization and is now usable. When the shop is a storefront that was removed from DoctorX and connected again, it is a new shop with a new id: previousShopIds lists the removed ids it replaces, and every API key that was bound to one of them is now bound to this shop instead (absent when it replaces none).
shop.disconnectedA shop was removed from DoctorX by the seller. An API key bound to it keeps the id (it matches nothing, and the key never widens to other shops); when the same storefront is connected again, shop.connected names this id in previousShopIds and the key is bound to the new shop.
shop.token_revokedThe marketplace revoked the grant (seller uninstalled the app, or refresh failed permanently).
template.createdA reusable template was created.
template.updatedA reusable template changed.
template.deletedA reusable template was deleted.
product.createdA product was created in DoctorX, including an Etsy or Amazon listing DoctorX imported from the marketplace (source: "PULLED", with shopId).
product.updatedA product’s content, price, variants or attributes changed, or (Etsy, Amazon) what the marketplace says about its listing: changedFields names listing.* fields then (source: "marketplace_sync"). Products combined into one listing in the dashboard, designs of such a listing renamed, reordered or removed there, and products given back when their design is removed or the listing is deleted, fire it with source: "merge": the listing names variants, mergeAxis and designs in changedFields, and each product combined into it, moved to it from another combined listing, or given back names mergedIntoId and mergedAt. The daily counters (shopSyncs[].metrics) change without an event.
product.deletedA product was deleted in DoctorX. marketplaceListingEnded: false when a person deleted it: the marketplace listing keeps running. true when DoctorX removed its copy of an Etsy or Amazon listing that was removed on the marketplace (source: "marketplace_sync", with shopId); a copy that has orders or DoctorX work on it is kept instead, with shopSyncs[].listing.channelStatus saying the listing is gone. Also false when a shop was removed from DoctorX and the products it had imported went with it, shortly after the removal (source: "shop_removed", with shopId, normally one event for the whole shop): only imported products nothing in DoctorX was built on (no orders, template, design SKU, cross-listing group or media edits) are removed, and the listings keep running on the marketplace.
product.publishedOne or more products were published to at least one shop. ONE EVENT DESCRIBES ONE PUBLISH RUN, not one API call: productIds lists everything the run published, and several of your calls can share one event, so read productIds rather than counting events against calls. A published product normally reads synced on the shop. On a TikTok shop at its listing limit it can first read pending without externalProductId, usually for a few minutes, before it reads synced; if TikTok’s review refuses it instead, a product.publish_failed follows for the same product and shop.
product.publish_failedA publish failed, or a product stopped holding its listing without one: the marketplace removed the listing, or the listing is no longer this product’s. failures[] carries one entry per (product, shop) with the channel code (null when DoctorX reports the outcome itself), DoctorX’s helpId, whether it is retryable, the channel’s docUrl, and any media assets the channel named as the cause (url, role, detail, plus heldBy when the listing sent that file without holding it, as on the product’s shopSyncs[].assetErrors). reasons[] is the same information as pre-formatted strings and is kept for existing subscribers. ONE FAILURE IS NOT ALWAYS FINAL. After helpId capacityReachedDuringPublish (the TikTok shop reached its listing limit while the publish ran) DoctorX publishes the product again by itself, so a product.published or another product.publish_failed for the same product and shop follows: do not retry it yourself. After a failure marked retryable DoctorX may also try again by itself, a limited number of times; if the pair still reads failed after that, retrying is up to you.
product.audit_status_changedThe marketplace review verdict changed (e.g. APPROVED -> FAILED). A synced push can still be rejected.
product.listing_endedA live marketplace listing was ended without deleting the local product.
shop.sync_state_changedEtsy and Amazon: the marketplace connection's reading of this shop changed state (active, paused, inactive, disconnected). Carries previousState (null at the first reading, which is reported only when the shop is not active), state and sourceSyncedAt (when it last finished reading the marketplace). While a shop is not active, its new orders and listing changes do not reach DoctorX.
order.createdA new order was ingested from the marketplace.
order.updatedAn ingested order changed something you can act on: its status, fulfilment status, tracking number, a line's personalisation note (Etsy and Amazon, when it arrives or changes after the order), or a marketplace amount - the discount split itemsBreakdown, the shipping split shippingBreakdown and retailDeliveryFee included, when one appears, disappears or moves by a cent. A re-read that changed nothing fires nothing, and neither does a DoctorX-side edit such as a cost of goods. It also fires when a settlement statement covering the order is reconciled (on Amazon, when its per-order fee report states a new fee for the order) AND one of its fee fields moved: source is then settlement_reconciled and only the fee fields and channelEarning moved. Reading the same statement again fires nothing.
order.status_changedThe order status transitioned, whichever side moved it; the payload carries both old and new, and source says who: marketplace, doctorx, fulfillment (the print provider's tracking) or carrier (DoctorX's carrier tracking).
order.cancelledThe order was cancelled, by the marketplace or in DoctorX; source is marketplace or doctorx.
order.tracking_updatedA tracking number was attached or changed, or the parcel's status advanced, whichever side did it; source says who (marketplace, doctorx for a number entered, imported or minted by a label, fulfillment, carrier). Carries carrier, trackingNumber, trackingStatus when known, and pushedToChannel when DoctorX knows whether the marketplace has the number.
order.return_createdA return or refund was opened against the order.
order.return_updatedAn existing return changed: most often its status advanced (e.g. REFUND_PROCESSING -> REFUND_SUCCESS), which is when the money actually moves. The payload carries both the previous and the new status. Fires only on a real change, never on a re-pull of unchanged data.
ebay.policy.createdAn eBay business policy was created, from either the API or the dashboard. Publish readiness may have changed.
ebay.policy.updatedAn eBay business policy changed IN PLACE on eBay, so every live offer using it is affected.
ebay.policy.deletedAn eBay business policy was deleted on eBay. If it was the default, publish will refuse until another is made default.
ebay.location.createdAn eBay inventory location was created.
ebay.location.updatedAn eBay inventory location address or name changed.
ebay.location.deletedAn eBay inventory location was deleted. Offers referencing its merchantLocationKey are affected.
etsy.policy.createdAn Etsy shipping profile, return policy, processing profile or shop section was created, from either the API or the dashboard. type says which. Publish readiness may have changed.
etsy.policy.updatedAn Etsy profile changed, OR became the default for its kind. A default change decides which profile every future publish binds, so it fires here too.
etsy.policy.deletedAn Etsy profile was deleted. If it was the default of a required kind (shipping, return or processing), publish will refuse until another is made default. The payload describes the profile as it was, since it no longer exists to look up.
etsy.personalization.createdAn Etsy personalization template was created. Templates are workspace-scoped, not shop-scoped.
etsy.personalization.updatedAn Etsy personalization template changed.
etsy.personalization.deletedAn Etsy personalization template was deleted. Listings already carrying it are unaffected.
finance.payout_recordedDoctorX stored a payout it had not seen before. The payout itself may be older; this fires on first sight, and amounts are decimal strings with a currency.
finance.ledger_entry_recordedAn Etsy or Amazon ledger row (a payment, a fee, a refund, a tax line) that DoctorX stored for the first time. Fires once per row, when the shop's ledger is read (every 6 hours), at most about 60 a minute per shop in the order DoctorX recorded them, so a backlog arrives at that pace; the shop's first full read announces nothing. The payload names the row (ledgerEntryId, the id of GET /finances/ledger-entries), its shop, date, type, signed amount in the row's own currency and the marketplace order it names, if any.

Payload

The body of every delivery (WebhookEventPayload).

idstringrequired

Unique event id. Use it to de-duplicate: a retry reuses the same id.

typestringrequired

Event type from the DoctorX catalog.

One of: "shop.connected", "shop.disconnected", "shop.token_revoked", "template.created", "template.updated", "template.deleted", "product.created", "product.updated", "product.deleted", "product.published", "product.publish_failed", "product.audit_status_changed", "product.listing_ended", "shop.sync_state_changed", "order.created", "order.updated", "order.status_changed", "order.cancelled", "order.tracking_updated", "order.return_created", "order.return_updated", "ebay.policy.created", "ebay.policy.updated", "ebay.policy.deleted", "ebay.location.created", "ebay.location.updated", "ebay.location.deleted", "etsy.policy.created", "etsy.policy.updated", "etsy.policy.deleted", "etsy.personalization.created", "etsy.personalization.updated", "etsy.personalization.deleted", "finance.payout_recorded", "finance.ledger_entry_recorded"

schemaVersionintegerrequired

Payload schema version for data. Currently 1.

min -9007199254740991 · max 9007199254740991

createdAtstring (date-time) | string (date)required

When the event was generated, not when it was delivered.

orgIdstringrequired

Tenant the event belongs to.

dataobjectrequired

Event-specific body; see the event catalog.

Verify a signature

The TypeScript verifier is the one DoctorX ships and tests; the Python one implements the same check. Pass the raw request body, exactly as received.

import { createHmac, timingSafeEqual } from 'node:crypto';

export const WEBHOOK_SKEW_SECONDS = 300;

export function signWebhook(
  secret: string,
  timestamp: string,
  rawBody: string,
): string {
  return createHmac('sha256', secret)
    .update(`${timestamp}\n${rawBody}`)
    .digest('hex');
}

export function verifyWebhookSignature(
  secret: string,
  timestamp: string | undefined,
  rawBody: string,
  headerValue: string | undefined,
  nowUnix: number = Math.floor(Date.now() / 1000),
): boolean {
  if (!timestamp || !headerValue) return false;
  const ts = Number(timestamp);
  if (!Number.isFinite(ts) || Math.abs(nowUnix - ts) > WEBHOOK_SKEW_SECONDS) {
    return false;
  }
  const presented = headerValue.startsWith('sha256=')
    ? headerValue.slice('sha256='.length)
    : headerValue;
  const expected = signWebhook(secret, timestamp, rawBody);
  if (expected.length !== presented.length) return false;
  try {
    return timingSafeEqual(Buffer.from(expected), Buffer.from(presented));
  } catch {
    return false;
  }
}