// api reference

Webhooks

GETList webhook endpoints
POSTRegister a webhook endpoint
GETRetrieve a webhook endpoint
PATCHUpdate a webhook endpoint, or turn it off and on
DELETEDelete a webhook endpoint and its deliveries
POSTReplace the signing secret
GETRecent deliveries, newest first, with request and response
GETRetrieve a delivery
POSTSend a delivery again
GETEvents, newest first: every state change on every resource
GETRetrieve an event

GET /v1/webhook_endpoints

List webhook endpoints

secret key only

GET /v1/webhook_endpointsrequest

curl https://api.marketsdk.com/v1/webhook_endpoints \
  -H "Authorization: Bearer $MARKETSDK_KEY"

200 example response, webhook endpoint list

{
  "object": "list",
  "data": [
    {
      "object": "webhook_endpoint",
      "id": "whe_034XtPDs7UJ0TXzTsdaHZa",
      "url": "string",
      "description": null,
      "enabled_events": [
        "string"
      ],
      "status": "enabled",
      "disabled_reason": null,
      "failing_since": null,
      "last_success_at": null,
      "secret": "string",
      "metadata": {},
      "created_at": "2026-10-01T12:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

parameters

Parameters
field	type	about
limit	integer, in query	min 1, max 100, default 20
starting_after	string, in query	The `next_cursor` of the previous page.

returns 200, webhook endpoint list

fields

Response fields
field	type	about
objectrequired	one of: list
datarequired	array of webhook endpoint
data[].objectrequired	one of: webhook_endpoint
data[].idrequired	string
data[].urlrequired	string
data[].descriptionrequired	string or null
data[].enabled_eventsrequired	array of string
data[].statusrequired	one of: enabled, disabled
data[].disabled_reasonrequired	string or null	Why it was turned off, when MarketSDK turned it off.
data[].failing_sincerequired	timestamp or null	Every delivery has failed since this time.
data[].last_success_atrequired	timestamp or null
data[].secret	string	The signing secret. Returned only when the endpoint is created or its secret rotated.
data[].metadatarequired	object of strings
data[].created_atrequired	timestamp
has_morerequired	boolean	Whether another page follows.
next_cursorrequired	string or null	Pass as `starting_after` (or `cursor` for search) to get the next page.

errors

400The request is not valid.
401No API key, or not a valid one.
429Rate limited. See Retry-After.

POST /v1/webhook_endpoints

Register a webhook endpoint

Returns the signing secret, once. Every delivery carries MarketSDK-Signature: t=<time>,v1=<HMAC-SHA256 of "<time>.<body>">.

secret key only

POST /v1/webhook_endpointsrequest

curl -X POST https://api.marketsdk.com/v1/webhook_endpoints \
  -H "Authorization: Bearer $MARKETSDK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"url":"https://shop.example/marketsdk/webhooks","enabled_events":["*"]}'

201 example response, webhook endpoint

{
  "object": "webhook_endpoint",
  "id": "whe_034XtPDs7UJ0TXzTsdaHZa",
  "url": "string",
  "description": null,
  "enabled_events": [
    "string"
  ],
  "status": "enabled",
  "disabled_reason": null,
  "failing_since": null,
  "last_success_at": null,
  "secret": "string",
  "metadata": {},
  "created_at": "2026-10-01T12:00:00.000Z"
}

body, create webhook endpoint

Request body
field	type	about
urlrequired	string	An HTTPS URL on the public internet.
enabled_eventsrequired	array of one of: *, seller.created, seller.updated, seller.erased, seller.suspended, seller.unsuspended, seller.verification_updated, seller.payouts_updated, buyer.created, buyer.updated, buyer.erased, category.created, category.updated, listing.created, listing.updated, listing.published, listing.unpublished, listing.sold, listing.expired, listing.removed, media.ready, media.deleted, order.created, order.committed, order.claimed, order.cancellation_proposed, order.cancellation_declined, order.cancelled, order.expired, order.completed, order.disputed, payment.created, payment.succeeded, payment.failed, payment.canceled, payment.refunded, payment.released, payment.release_failed, refund.created, refund.updated, verification.created, verification.updated, review.created, review.visible, review.removed, reputation_event.created, reputation_event.voided, dispute.created, dispute.evidence_added, dispute.updated, dispute.decision_overdue, dispute.decided, card_dispute.created, card_dispute.updated, flag.created, flag.resolved, moderation_action.created	Event types to send, or `*` for all.
description	string	up to 200 characters
metadata	object of strings

returns 201, webhook endpoint

fields

Response fields
field	type	about
objectrequired	one of: webhook_endpoint
idrequired	string
urlrequired	string
descriptionrequired	string or null
enabled_eventsrequired	array of string
statusrequired	one of: enabled, disabled
disabled_reasonrequired	string or null	Why it was turned off, when MarketSDK turned it off.
failing_sincerequired	timestamp or null	Every delivery has failed since this time.
last_success_atrequired	timestamp or null
secret	string	The signing secret. Returned only when the endpoint is created or its secret rotated.
metadatarequired	object of strings
created_atrequired	timestamp

errors

400The request is not valid.
401No API key, or not a valid one.
429Rate limited. See Retry-After.

GET /v1/webhook_endpoints/{id}

Retrieve a webhook endpoint

secret key only

GET /v1/webhook_endpoints/{id}request

curl https://api.marketsdk.com/v1/webhook_endpoints/{id} \
  -H "Authorization: Bearer $MARKETSDK_KEY"

200 example response, webhook endpoint

{
  "object": "webhook_endpoint",
  "id": "whe_034XtPDs7UJ0TXzTsdaHZa",
  "url": "string",
  "description": null,
  "enabled_events": [
    "string"
  ],
  "status": "enabled",
  "disabled_reason": null,
  "failing_since": null,
  "last_success_at": null,
  "secret": "string",
  "metadata": {},
  "created_at": "2026-10-01T12:00:00.000Z"
}

parameters

Parameters
field	type	about
idrequired	string, in path

returns 200, webhook endpoint

fields

Response fields
field	type	about
objectrequired	one of: webhook_endpoint
idrequired	string
urlrequired	string
descriptionrequired	string or null
enabled_eventsrequired	array of string
statusrequired	one of: enabled, disabled
disabled_reasonrequired	string or null	Why it was turned off, when MarketSDK turned it off.
failing_sincerequired	timestamp or null	Every delivery has failed since this time.
last_success_atrequired	timestamp or null
secret	string	The signing secret. Returned only when the endpoint is created or its secret rotated.
metadatarequired	object of strings
created_atrequired	timestamp

errors

400The request is not valid.
401No API key, or not a valid one.
404No object with that id in this marketplace.
429Rate limited. See Retry-After.

PATCH /v1/webhook_endpoints/{id}

Update a webhook endpoint, or turn it off and on

secret key only

PATCH /v1/webhook_endpoints/{id}request

curl -X PATCH https://api.marketsdk.com/v1/webhook_endpoints/{id} \
  -H "Authorization: Bearer $MARKETSDK_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

200 example response, webhook endpoint

{
  "object": "webhook_endpoint",
  "id": "whe_034XtPDs7UJ0TXzTsdaHZa",
  "url": "string",
  "description": null,
  "enabled_events": [
    "string"
  ],
  "status": "enabled",
  "disabled_reason": null,
  "failing_since": null,
  "last_success_at": null,
  "secret": "string",
  "metadata": {},
  "created_at": "2026-10-01T12:00:00.000Z"
}

parameters

Parameters
field	type	about
idrequired	string, in path

body, update webhook endpoint

Request body
field	type	about
url	string
enabled_events	array of one of: *, seller.created, seller.updated, seller.erased, seller.suspended, seller.unsuspended, seller.verification_updated, seller.payouts_updated, buyer.created, buyer.updated, buyer.erased, category.created, category.updated, listing.created, listing.updated, listing.published, listing.unpublished, listing.sold, listing.expired, listing.removed, media.ready, media.deleted, order.created, order.committed, order.claimed, order.cancellation_proposed, order.cancellation_declined, order.cancelled, order.expired, order.completed, order.disputed, payment.created, payment.succeeded, payment.failed, payment.canceled, payment.refunded, payment.released, payment.release_failed, refund.created, refund.updated, verification.created, verification.updated, review.created, review.visible, review.removed, reputation_event.created, reputation_event.voided, dispute.created, dispute.evidence_added, dispute.updated, dispute.decision_overdue, dispute.decided, card_dispute.created, card_dispute.updated, flag.created, flag.resolved, moderation_action.created
description	string	up to 200 characters
status	one of: enabled, disabled	Turn the endpoint off, or back on after it was turned off.
metadata	object of strings

returns 200, webhook endpoint

fields

Response fields
field	type	about
objectrequired	one of: webhook_endpoint
idrequired	string
urlrequired	string
descriptionrequired	string or null
enabled_eventsrequired	array of string
statusrequired	one of: enabled, disabled
disabled_reasonrequired	string or null	Why it was turned off, when MarketSDK turned it off.
failing_sincerequired	timestamp or null	Every delivery has failed since this time.
last_success_atrequired	timestamp or null
secret	string	The signing secret. Returned only when the endpoint is created or its secret rotated.
metadatarequired	object of strings
created_atrequired	timestamp

errors

400The request is not valid.
401No API key, or not a valid one.
404No object with that id in this marketplace.
429Rate limited. See Retry-After.

DELETE /v1/webhook_endpoints/{id}

Delete a webhook endpoint and its deliveries

secret key only

DELETE /v1/webhook_endpoints/{id}request

curl -X DELETE https://api.marketsdk.com/v1/webhook_endpoints/{id} \
  -H "Authorization: Bearer $MARKETSDK_KEY"

200 example response, deleted webhook endpoint

{
  "object": "webhook_endpoint",
  "id": "string",
  "deleted": true
}

parameters

Parameters
field	type	about
idrequired	string, in path

returns 200, deleted webhook endpoint

fields

Response fields
field	type	about
objectrequired	one of: webhook_endpoint
idrequired	string
deletedrequired	one of: true

errors

400The request is not valid.
401No API key, or not a valid one.
404No object with that id in this marketplace.
429Rate limited. See Retry-After.

POST /v1/webhook_endpoints/{id}/rotate_secret

Replace the signing secret

Returns the new secret, once. The old one stops at once.

secret key only

POST /v1/webhook_endpoints/{id}/rotate_secretrequest

curl -X POST https://api.marketsdk.com/v1/webhook_endpoints/{id}/rotate_secret \
  -H "Authorization: Bearer $MARKETSDK_KEY"

200 example response, webhook endpoint

{
  "object": "webhook_endpoint",
  "id": "whe_034XtPDs7UJ0TXzTsdaHZa",
  "url": "string",
  "description": null,
  "enabled_events": [
    "string"
  ],
  "status": "enabled",
  "disabled_reason": null,
  "failing_since": null,
  "last_success_at": null,
  "secret": "string",
  "metadata": {},
  "created_at": "2026-10-01T12:00:00.000Z"
}

parameters

Parameters
field	type	about
idrequired	string, in path

returns 200, webhook endpoint

fields

Response fields
field	type	about
objectrequired	one of: webhook_endpoint
idrequired	string
urlrequired	string
descriptionrequired	string or null
enabled_eventsrequired	array of string
statusrequired	one of: enabled, disabled
disabled_reasonrequired	string or null	Why it was turned off, when MarketSDK turned it off.
failing_sincerequired	timestamp or null	Every delivery has failed since this time.
last_success_atrequired	timestamp or null
secret	string	The signing secret. Returned only when the endpoint is created or its secret rotated.
metadatarequired	object of strings
created_atrequired	timestamp

errors

400The request is not valid.
401No API key, or not a valid one.
404No object with that id in this marketplace.
429Rate limited. See Retry-After.

GET /v1/webhook_deliveries

Recent deliveries, newest first, with request and response

secret key only

GET /v1/webhook_deliveriesrequest

curl https://api.marketsdk.com/v1/webhook_deliveries \
  -H "Authorization: Bearer $MARKETSDK_KEY"

200 example response, webhook delivery list

{
  "object": "list",
  "data": [
    {
      "object": "webhook_delivery",
      "id": "whd_034XtPDs7UJ0TXzTsdaHZa",
      "endpoint": "string",
      "event": "string",
      "event_type": "string",
      "replay_of": null,
      "status": "pending",
      "attempts": 0,
      "attempt_log": [
        {
          "at": null,
          "status": null,
          "duration_ms": null,
          "error": null
        }
      ],
      "next_attempt_at": null,
      "request": {
        "headers": {},
        "body": "string"
      },
      "response": {
        "status": null,
        "body": null
      },
      "error": null,
      "created_at": "2026-10-01T12:00:00.000Z",
      "completed_at": null
    }
  ],
  "has_more": false,
  "next_cursor": null
}

parameters

Parameters
field	type	about
limit	integer, in query	min 1, max 100, default 20
starting_after	string, in query	The `next_cursor` of the previous page.
endpoint	string, in query
status	one of: pending, succeeded, failed, in query

returns 200, webhook delivery list

fields

Response fields
field	type	about
objectrequired	one of: list
datarequired	array of webhook delivery
data[].objectrequired	one of: webhook_delivery
data[].idrequired	string
data[].endpointrequired	string
data[].eventrequired	string
data[].event_typerequired	string
data[].replay_ofrequired	string or null	The delivery this one replays.
data[].statusrequired	one of: pending, succeeded, failed
data[].attemptsrequired	integer
data[].attempt_logrequired	array of delivery attempt
data[].attempt_log[].atrequired	timestamp
data[].attempt_log[].statusrequired	integer or null	The HTTP status your endpoint answered with, or null if it did not answer.
data[].attempt_log[].duration_msrequired	integer
data[].attempt_log[].errorrequired	string or null
data[].next_attempt_atrequired	timestamp or null
data[].requestrequired	webhook delivery request
data[].request.headersrequired	object of strings
data[].request.bodyrequired	string	The exact body sent.
data[].responserequired	webhook delivery response
data[].response.statusrequired	integer or null
data[].response.bodyrequired	string or null	The first 4,096 characters.
data[].errorrequired	string or null	Why the last attempt failed.
data[].created_atrequired	timestamp
data[].completed_atrequired	timestamp or null
has_morerequired	boolean	Whether another page follows.
next_cursorrequired	string or null	Pass as `starting_after` (or `cursor` for search) to get the next page.

errors

400The request is not valid.
401No API key, or not a valid one.
429Rate limited. See Retry-After.

GET /v1/webhook_deliveries/{id}

Retrieve a delivery

secret key only

GET /v1/webhook_deliveries/{id}request

curl https://api.marketsdk.com/v1/webhook_deliveries/{id} \
  -H "Authorization: Bearer $MARKETSDK_KEY"

200 example response, webhook delivery

{
  "object": "webhook_delivery",
  "id": "whd_034XtPDs7UJ0TXzTsdaHZa",
  "endpoint": "string",
  "event": "string",
  "event_type": "string",
  "replay_of": null,
  "status": "pending",
  "attempts": 0,
  "attempt_log": [
    {
      "at": "2026-10-01T12:00:00.000Z",
      "status": null,
      "duration_ms": 0,
      "error": null
    }
  ],
  "next_attempt_at": null,
  "request": {
    "headers": {},
    "body": "string"
  },
  "response": {
    "status": null,
    "body": null
  },
  "error": null,
  "created_at": "2026-10-01T12:00:00.000Z",
  "completed_at": null
}

parameters

Parameters
field	type	about
idrequired	string, in path

returns 200, webhook delivery

fields

Response fields
field	type	about
objectrequired	one of: webhook_delivery
idrequired	string
endpointrequired	string
eventrequired	string
event_typerequired	string
replay_ofrequired	string or null	The delivery this one replays.
statusrequired	one of: pending, succeeded, failed
attemptsrequired	integer
attempt_logrequired	array of delivery attempt
attempt_log[].atrequired	timestamp
attempt_log[].statusrequired	integer or null	The HTTP status your endpoint answered with, or null if it did not answer.
attempt_log[].duration_msrequired	integer
attempt_log[].errorrequired	string or null
next_attempt_atrequired	timestamp or null
requestrequired	webhook delivery request
request.headersrequired	object of strings
request.bodyrequired	string	The exact body sent.
responserequired	webhook delivery response
response.statusrequired	integer or null
response.bodyrequired	string or null	The first 4,096 characters.
errorrequired	string or null	Why the last attempt failed.
created_atrequired	timestamp
completed_atrequired	timestamp or null

errors

400The request is not valid.
401No API key, or not a valid one.
404No object with that id in this marketplace.
429Rate limited. See Retry-After.

POST /v1/webhook_deliveries/{id}/replay

Send a delivery again

Creates a new delivery of the same event to the same endpoint.

secret key only

POST /v1/webhook_deliveries/{id}/replayrequest

curl -X POST https://api.marketsdk.com/v1/webhook_deliveries/{id}/replay \
  -H "Authorization: Bearer $MARKETSDK_KEY"

201 example response, webhook delivery

{
  "object": "webhook_delivery",
  "id": "whd_034XtPDs7UJ0TXzTsdaHZa",
  "endpoint": "string",
  "event": "string",
  "event_type": "string",
  "replay_of": null,
  "status": "pending",
  "attempts": 0,
  "attempt_log": [
    {
      "at": "2026-10-01T12:00:00.000Z",
      "status": null,
      "duration_ms": 0,
      "error": null
    }
  ],
  "next_attempt_at": null,
  "request": {
    "headers": {},
    "body": "string"
  },
  "response": {
    "status": null,
    "body": null
  },
  "error": null,
  "created_at": "2026-10-01T12:00:00.000Z",
  "completed_at": null
}

parameters

Parameters
field	type	about
idrequired	string, in path

returns 201, webhook delivery

fields

Response fields
field	type	about
objectrequired	one of: webhook_delivery
idrequired	string
endpointrequired	string
eventrequired	string
event_typerequired	string
replay_ofrequired	string or null	The delivery this one replays.
statusrequired	one of: pending, succeeded, failed
attemptsrequired	integer
attempt_logrequired	array of delivery attempt
attempt_log[].atrequired	timestamp
attempt_log[].statusrequired	integer or null	The HTTP status your endpoint answered with, or null if it did not answer.
attempt_log[].duration_msrequired	integer
attempt_log[].errorrequired	string or null
next_attempt_atrequired	timestamp or null
requestrequired	webhook delivery request
request.headersrequired	object of strings
request.bodyrequired	string	The exact body sent.
responserequired	webhook delivery response
response.statusrequired	integer or null
response.bodyrequired	string or null	The first 4,096 characters.
errorrequired	string or null	Why the last attempt failed.
created_atrequired	timestamp
completed_atrequired	timestamp or null

errors

400The request is not valid.
401No API key, or not a valid one.
404No object with that id in this marketplace.
409The object is not in a state that allows this.
429Rate limited. See Retry-After.

GET /v1/events

Events, newest first: every state change on every resource

secret key only

GET /v1/eventsrequest

curl https://api.marketsdk.com/v1/events \
  -H "Authorization: Bearer $MARKETSDK_KEY"

200 example response, event list

{
  "object": "list",
  "data": [
    {
      "object": "event",
      "id": "evt_034XtPDs7UJ0TXzTsdaHZa",
      "type": "seller.created",
      "api_version": "string",
      "created": "2026-10-01T12:00:00.000Z",
      "livemode": false,
      "data": {}
    }
  ],
  "has_more": false,
  "next_cursor": null
}

parameters

Parameters
field	type	about
limit	integer, in query	min 1, max 100, default 20
starting_after	string, in query	The `next_cursor` of the previous page.
type	one of: seller.created, seller.updated, seller.erased, seller.suspended, seller.unsuspended, seller.verification_updated, seller.payouts_updated, buyer.created, buyer.updated, buyer.erased, category.created, category.updated, listing.created, listing.updated, listing.published, listing.unpublished, listing.sold, listing.expired, listing.removed, media.ready, media.deleted, order.created, order.committed, order.claimed, order.cancellation_proposed, order.cancellation_declined, order.cancelled, order.expired, order.completed, order.disputed, payment.created, payment.succeeded, payment.failed, payment.canceled, payment.refunded, payment.released, payment.release_failed, refund.created, refund.updated, verification.created, verification.updated, review.created, review.visible, review.removed, reputation_event.created, reputation_event.voided, dispute.created, dispute.evidence_added, dispute.updated, dispute.decision_overdue, dispute.decided, card_dispute.created, card_dispute.updated, flag.created, flag.resolved, moderation_action.created, in query

returns 200, event list

fields

Response fields
field	type	about
objectrequired	one of: list
datarequired	array of event
data[].objectrequired	one of: event
data[].idrequired	string
data[].typerequired	one of: seller.created, seller.updated, seller.erased, seller.suspended, seller.unsuspended, seller.verification_updated, seller.payouts_updated, buyer.created, buyer.updated, buyer.erased, category.created, category.updated, listing.created, listing.updated, listing.published, listing.unpublished, listing.sold, listing.expired, listing.removed, media.ready, media.deleted, order.created, order.committed, order.claimed, order.cancellation_proposed, order.cancellation_declined, order.cancelled, order.expired, order.completed, order.disputed, payment.created, payment.succeeded, payment.failed, payment.canceled, payment.refunded, payment.released, payment.release_failed, refund.created, refund.updated, verification.created, verification.updated, review.created, review.visible, review.removed, reputation_event.created, reputation_event.voided, dispute.created, dispute.evidence_added, dispute.updated, dispute.decision_overdue, dispute.decided, card_dispute.created, card_dispute.updated, flag.created, flag.resolved, moderation_action.created
data[].api_versionrequired	string	Always v1 in this version of the API.
data[].createdrequired	timestamp
data[].livemoderequired	boolean
data[].datarequired	object of strings	`data.object` is the object as it was right after the change.
has_morerequired	boolean	Whether another page follows.
next_cursorrequired	string or null	Pass as `starting_after` (or `cursor` for search) to get the next page.

errors

400The request is not valid.
401No API key, or not a valid one.
429Rate limited. See Retry-After.

GET /v1/events/{id}

Retrieve an event

secret key only

GET /v1/events/{id}request

curl https://api.marketsdk.com/v1/events/{id} \
  -H "Authorization: Bearer $MARKETSDK_KEY"

200 example response, event

{
  "object": "event",
  "id": "evt_034XtPDs7UJ0TXzTsdaHZa",
  "type": "seller.created",
  "api_version": "string",
  "created": "2026-10-01T12:00:00.000Z",
  "livemode": false,
  "data": {}
}

parameters

Parameters
field	type	about
idrequired	string, in path

returns 200, event

fields

Response fields
field	type	about
objectrequired	one of: event
idrequired	string
typerequired	one of: seller.created, seller.updated, seller.erased, seller.suspended, seller.unsuspended, seller.verification_updated, seller.payouts_updated, buyer.created, buyer.updated, buyer.erased, category.created, category.updated, listing.created, listing.updated, listing.published, listing.unpublished, listing.sold, listing.expired, listing.removed, media.ready, media.deleted, order.created, order.committed, order.claimed, order.cancellation_proposed, order.cancellation_declined, order.cancelled, order.expired, order.completed, order.disputed, payment.created, payment.succeeded, payment.failed, payment.canceled, payment.refunded, payment.released, payment.release_failed, refund.created, refund.updated, verification.created, verification.updated, review.created, review.visible, review.removed, reputation_event.created, reputation_event.voided, dispute.created, dispute.evidence_added, dispute.updated, dispute.decision_overdue, dispute.decided, card_dispute.created, card_dispute.updated, flag.created, flag.resolved, moderation_action.created
api_versionrequired	string	Always v1 in this version of the API.
createdrequired	timestamp
livemoderequired	boolean
datarequired	object of strings	`data.object` is the object as it was right after the change.

errors

400The request is not valid.
401No API key, or not a valid one.
404No object with that id in this marketplace.
429Rate limited. See Retry-After.