DoctorX logoDoctorX Get an API key

Webhooks

Event subscriptions, deliveries and signature verification.

GET/webhooks/events

Every event type with its meaning and payload schema version. Enumerate this instead of hard-coding the list.

Responses

200WebhookEventCatalogResponse
StatusMeaning (body: error envelope)
400

Validation failed, or the request is not valid for this resource.

401

The API key is missing, unknown, revoked or expired.

403

The API key lacks the required scope, or is not bound to this shop.

404

No such resource for this tenant.

409

The request conflicts with the current state (see error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X GET 'https://api.doctorx.vn/api/public/v1/webhooks/events' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"
GET/webhooks/endpoints

Responses

200WebhookEndpointListResponse
StatusMeaning (body: error envelope)
400

Validation failed, or the request is not valid for this resource.

401

The API key is missing, unknown, revoked or expired.

403

The API key lacks the required scope, or is not bound to this shop.

404

No such resource for this tenant.

409

The request conflicts with the current state (see error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X GET 'https://api.doctorx.vn/api/public/v1/webhooks/endpoints' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"
POST/webhooks/endpoints

The URL must be HTTPS and must resolve to a public address; a private, loopback or link-local host is refused. The signing secret is returned ONCE in this response and can afterwards only be rotated, never read.

Request body

urlstring (uri)required

HTTPS only, and must resolve to a public address. A private or link-local host is refused to prevent server-side request forgery.

eventsstring[]

Subscribed events. Empty subscribes to everything.

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"

default []

Responses

201CreatedWebhookEndpointResponse
StatusMeaning (body: error envelope)
400

Validation failed, or the request is not valid for this resource.

401

The API key is missing, unknown, revoked or expired.

403

The API key lacks the required scope, or is not bound to this shop.

404

No such resource for this tenant.

409

The request conflicts with the current state (see error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X POST 'https://api.doctorx.vn/api/public/v1/webhooks/endpoints' \
  -H "Authorization: Bearer $DOCTORX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com"
}'
GET/webhooks/endpoints/{id}

Parameters

NameInTypeDescription
idrequired
pathstring

Responses

200WebhookEndpointResponse
StatusMeaning (body: error envelope)
400

Validation failed, or the request is not valid for this resource.

401

The API key is missing, unknown, revoked or expired.

403

The API key lacks the required scope, or is not bound to this shop.

404

No such resource for this tenant.

409

The request conflicts with the current state (see error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X GET 'https://api.doctorx.vn/api/public/v1/webhooks/endpoints/string' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"
PATCH/webhooks/endpoints/{id}

Send active: true to re-enable an endpoint the circuit breaker disabled after repeated failures; that also clears the failure counter.

Parameters

NameInTypeDescription
idrequired
pathstring

Request body

urlstring (uri)
eventsstring[]

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"

activeboolean

Set true to re-enable an endpoint the circuit breaker disabled; the events held while it was off are then sent, oldest first. Set false to switch it off yourself: nothing is held from then on.

Responses

200WebhookEndpointResponse
StatusMeaning (body: error envelope)
400

Validation failed, or the request is not valid for this resource.

401

The API key is missing, unknown, revoked or expired.

403

The API key lacks the required scope, or is not bound to this shop.

404

No such resource for this tenant.

409

The request conflicts with the current state (see error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X PATCH 'https://api.doctorx.vn/api/public/v1/webhooks/endpoints/string' \
  -H "Authorization: Bearer $DOCTORX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
DELETE/webhooks/endpoints/{id}

Also removes its delivery history.

Parameters

NameInTypeDescription
idrequired
pathstring

Responses

200DeleteResultResponse
StatusMeaning (body: error envelope)
400

Validation failed, or the request is not valid for this resource.

401

The API key is missing, unknown, revoked or expired.

403

The API key lacks the required scope, or is not bound to this shop.

404

No such resource for this tenant.

409

The request conflicts with the current state (see error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X DELETE 'https://api.doctorx.vn/api/public/v1/webhooks/endpoints/string' \
  -H "Authorization: Bearer $DOCTORX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
POST/webhooks/endpoints/{id}/rotate-secret

The new secret is returned once. Deliveries signed with the old secret stop verifying immediately, so swap it in before the next event.

Parameters

NameInTypeDescription
idrequired
pathstring

Responses

200CreatedWebhookEndpointResponse
StatusMeaning (body: error envelope)
400

Validation failed, or the request is not valid for this resource.

401

The API key is missing, unknown, revoked or expired.

403

The API key lacks the required scope, or is not bound to this shop.

404

No such resource for this tenant.

409

The request conflicts with the current state (see error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X POST 'https://api.doctorx.vn/api/public/v1/webhooks/endpoints/string/rotate-secret' \
  -H "Authorization: Bearer $DOCTORX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
POST/webhooks/endpoints/{id}/test

Delivers synchronously and echoes the exact signature and timestamp that were sent, so a receiver can be validated against real signing material in one request. Not recorded in the delivery log.

Parameters

NameInTypeDescription
idrequired
pathstring

Responses

200WebhookTestResultResponse
StatusMeaning (body: error envelope)
400

Validation failed, or the request is not valid for this resource.

401

The API key is missing, unknown, revoked or expired.

403

The API key lacks the required scope, or is not bound to this shop.

404

No such resource for this tenant.

409

The request conflicts with the current state (see error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X POST 'https://api.doctorx.vn/api/public/v1/webhooks/endpoints/string/test' \
  -H "Authorization: Bearer $DOCTORX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
GET/webhooks/deliveries

Attempt history with the receiver's status and body. Retained for 30 days.

Parameters

NameInTypeDescription
limit
queryinteger

Page size, 1..200. Defaults to 50.

min 1 · max 200 · default 50

cursor
querystring

Opaque cursor from a previous response meta.pagination.nextCursor.

order
querystring

Sort direction on the collection sort key.

One of: "asc", "desc"

default "desc"

includeTotal
querystring

When true, meta.pagination.total carries the full matching count (an extra COUNT query).

endpointId
querystring

DoctorX resource id: a UUID in canonical 8-4-4-4-12 hex form. Version and variant bits are not constrained.

pattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

eventType
querystring

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"

status
querystring

One of: "PENDING", "RETRYING", "DELIVERED", "FAILED", "BLOCKED", "HELD"

Responses

200WebhookDeliveryListResponse
StatusMeaning (body: error envelope)
400

Validation failed, or the request is not valid for this resource.

401

The API key is missing, unknown, revoked or expired.

403

The API key lacks the required scope, or is not bound to this shop.

404

No such resource for this tenant.

409

The request conflicts with the current state (see error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X GET 'https://api.doctorx.vn/api/public/v1/webhooks/deliveries' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"
GET/webhooks/deliveries/{id}

Parameters

NameInTypeDescription
idrequired
pathstring

Responses

200WebhookDeliveryResponse
StatusMeaning (body: error envelope)
400

Validation failed, or the request is not valid for this resource.

401

The API key is missing, unknown, revoked or expired.

403

The API key lacks the required scope, or is not bound to this shop.

404

No such resource for this tenant.

409

The request conflicts with the current state (see error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X GET 'https://api.doctorx.vn/api/public/v1/webhooks/deliveries/string' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"
POST/webhooks/deliveries/{id}/replay

Re-queues the same event with the same event id, so a receiver de-duplicating on X-DoctorX-Event-Id recognises it. The attempt counter continues rather than resetting: a replay is another attempt in this event’s history.

Parameters

NameInTypeDescription
idrequired
pathstring

Responses

200WebhookDeliveryResponse
StatusMeaning (body: error envelope)
400

Validation failed, or the request is not valid for this resource.

401

The API key is missing, unknown, revoked or expired.

403

The API key lacks the required scope, or is not bound to this shop.

404

No such resource for this tenant.

409

The request conflicts with the current state (see error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X POST 'https://api.doctorx.vn/api/public/v1/webhooks/deliveries/string/replay' \
  -H "Authorization: Bearer $DOCTORX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"