Webhooks
Event subscriptions, deliveries and signature verification.
/webhooks/eventsEvery event type with its meaning and payload schema version. Enumerate this instead of hard-coding the list.
Responses
| Status | Meaning (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 |
| 422 | The marketplace rejected the request; |
| 429 | Back off and retry. |
| 500 | A defect on our side ( |
Request sample
curl -X GET 'https://api.doctorx.vn/api/public/v1/webhooks/events' \
-H "Authorization: Bearer $DOCTORX_API_KEY"/webhooks/endpointsResponses
| Status | Meaning (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 |
| 422 | The marketplace rejected the request; |
| 429 | Back off and retry. |
| 500 | A defect on our side ( |
Request sample
curl -X GET 'https://api.doctorx.vn/api/public/v1/webhooks/endpoints' \
-H "Authorization: Bearer $DOCTORX_API_KEY"/webhooks/endpointsThe 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)requiredHTTPS 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
| Status | Meaning (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 |
| 422 | The marketplace rejected the request; |
| 429 | Back off and retry. |
| 500 | A defect on our side ( |
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"
}'/webhooks/endpoints/{id}Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
| Status | Meaning (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 |
| 422 | The marketplace rejected the request; |
| 429 | Back off and retry. |
| 500 | A defect on our side ( |
Request sample
curl -X GET 'https://api.doctorx.vn/api/public/v1/webhooks/endpoints/string' \
-H "Authorization: Bearer $DOCTORX_API_KEY"/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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
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"
activebooleanSet 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
| Status | Meaning (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 |
| 422 | The marketplace rejected the request; |
| 429 | Back off and retry. |
| 500 | A defect on our side ( |
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 '{}'/webhooks/endpoints/{id}Also removes its delivery history.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
| Status | Meaning (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 |
| 422 | The marketplace rejected the request; |
| 429 | Back off and retry. |
| 500 | A defect on our side ( |
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)"/webhooks/endpoints/{id}/rotate-secretThe new secret is returned once. Deliveries signed with the old secret stop verifying immediately, so swap it in before the next event.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
| Status | Meaning (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 |
| 422 | The marketplace rejected the request; |
| 429 | Back off and retry. |
| 500 | A defect on our side ( |
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)"/webhooks/endpoints/{id}/testDelivers 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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
| Status | Meaning (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 |
| 422 | The marketplace rejected the request; |
| 429 | Back off and retry. |
| 500 | A defect on our side ( |
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)"/webhooks/deliveriesAttempt history with the receiver's status and body. Retained for 30 days.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
limit | query | integer | Page size, 1..200. Defaults to 50. min 1 · max 200 · default 50 |
cursor | query | string | Opaque cursor from a previous response meta.pagination.nextCursor. |
order | query | string | Sort direction on the collection sort key. One of: "asc", "desc" default "desc" |
includeTotal | query | string | When true, meta.pagination.total carries the full matching count (an extra COUNT query). |
endpointId | query | string | 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 | query | string | 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 | query | string | One of: "PENDING", "RETRYING", "DELIVERED", "FAILED", "BLOCKED", "HELD" |
Responses
| Status | Meaning (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 |
| 422 | The marketplace rejected the request; |
| 429 | Back off and retry. |
| 500 | A defect on our side ( |
Request sample
curl -X GET 'https://api.doctorx.vn/api/public/v1/webhooks/deliveries' \
-H "Authorization: Bearer $DOCTORX_API_KEY"/webhooks/deliveries/{id}Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
| Status | Meaning (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 |
| 422 | The marketplace rejected the request; |
| 429 | Back off and retry. |
| 500 | A defect on our side ( |
Request sample
curl -X GET 'https://api.doctorx.vn/api/public/v1/webhooks/deliveries/string' \
-H "Authorization: Bearer $DOCTORX_API_KEY"/webhooks/deliveries/{id}/replayRe-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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
| Status | Meaning (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 |
| 422 | The marketplace rejected the request; |
| 429 | Back off and retry. |
| 500 | A defect on our side ( |
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)"