MarketSDK Webhooks API

openapi: 3.2.0
info:
  title: Marketsdk Webhooks API
  version: 1.0.0
  contact: {}
  description: 'Operations tagged Webhooks across 2 of this provider''s published API definitions: marketsdk-openapi.json, marketsdk-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.marketsdk.com
tags:
- name: Webhooks
paths:
  /v1/webhook_endpoints:
    post:
      description: 'Returns the signing secret, once. Every delivery carries `MarketSDK-Signature: t=,v1=.">`.'
      operationId: createWebhookEndpoint
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookEndpointDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpointObject'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: No API key, or not a valid one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. See `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - bearer: []
      summary: Register a webhook endpoint
      tags:
      - Webhooks
    get:
      operationId: listWebhookEndpoints
      parameters:
      - name: limit
        required: false
        in: query
        schema:
          minimum: 1
          maximum: 100
          default: 20
          type: number
      - name: starting_after
        required: false
        in: query
        description: The `next_cursor` of the previous page.
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpointList'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: No API key, or not a valid one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. See `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - bearer: []
      summary: List webhook endpoints
      tags:
      - Webhooks
    servers:
    - url: https://api.marketsdk.com
  /v1/webhook_endpoints/{id}:
    get:
      operationId: getWebhookEndpoint
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpointObject'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: No API key, or not a valid one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: No object with that id in this marketplace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. See `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - bearer: []
      summary: Retrieve a webhook endpoint
      tags:
      - Webhooks
    patch:
      operationId: updateWebhookEndpoint
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWebhookEndpointDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpointObject'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: No API key, or not a valid one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: No object with that id in this marketplace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. See `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - bearer: []
      summary: Update a webhook endpoint, or turn it off and on
      tags:
      - Webhooks
    delete:
      operationId: deleteWebhookEndpoint
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletedWebhookEndpointObject'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: No API key, or not a valid one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: No object with that id in this marketplace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. See `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - bearer: []
      summary: Delete a webhook endpoint and its deliveries
      tags:
      - Webhooks
    servers:
    - url: https://api.marketsdk.com
  /v1/webhook_endpoints/{id}/rotate_secret:
    post:
      description: Returns the new secret, once. The old one stops at once.
      operationId: rotateWebhookSecret
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpointObject'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: No API key, or not a valid one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: No object with that id in this marketplace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. See `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - bearer: []
      summary: Replace the signing secret
      tags:
      - Webhooks
    servers:
    - url: https://api.marketsdk.com
  /v1/webhook_deliveries:
    get:
      operationId: listWebhookDeliveries
      parameters:
      - name: limit
        required: false
        in: query
        schema:
          minimum: 1
          maximum: 100
          default: 20
          type: number
      - name: starting_after
        required: false
        in: query
        description: The `next_cursor` of the previous page.
        schema:
          type: string
      - name: endpoint
        required: false
        in: query
        schema:
          type: string
      - name: status
        required: false
        in: query
        schema:
          type: string
          enum:
          - pending
          - succeeded
          - failed
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookDeliveryList'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: No API key, or not a valid one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. See `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - bearer: []
      summary: Recent deliveries, newest first, with request and response
      tags:
      - Webhooks
    servers:
    - url: https://api.marketsdk.com
  /v1/webhook_deliveries/{id}:
    get:
      operationId: getWebhookDelivery
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookDeliveryObject'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: No API key, or not a valid one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: No object with that id in this marketplace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. See `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - bearer: []
      summary: Retrieve a delivery
      tags:
      - Webhooks
    servers:
    - url: https://api.marketsdk.com
  /v1/webhook_deliveries/{id}/replay:
    post:
      description: Creates a new delivery of the same event to the same endpoint.
      operationId: replayWebhookDelivery
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookDeliveryObject'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: No API key, or not a valid one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: No object with that id in this marketplace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: The object is not in a state that allows this.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. See `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - bearer: []
      summary: Send a delivery again
      tags:
      - Webhooks
    servers:
    - url: https://api.marketsdk.com
  /v1/events:
    get:
      operationId: listEvents
      parameters:
      - name: limit
        required: false
        in: query
        schema:
          minimum: 1
          maximum: 100
          default: 20
          type: number
      - name: starting_after
        required: false
        in: query
        description: The `next_cursor` of the previous page.
        schema:
          type: string
      - name: type
        required: false
        in: query
        schema:
          type: string
          enum:
          - 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
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventList'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: No API key, or not a valid one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. See `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - bearer: []
      summary: 'Events, newest first: every state change on every resource'
      tags:
      - Webhooks
    servers:
    - url: https://api.marketsdk.com
  /v1/events/{id}:
    get:
      operationId: getEvent
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventObject'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: No API key, or not a valid one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: No object with that id in this marketplace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. See `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - bearer: []
      summary: Retrieve an event
      tags:
      - Webhooks
    servers:
    - url: https://api.marketsdk.com
components:
  schemas:
    UpdateWebhookEndpointDto:
      type: object
      properties:
        url:
          type: string
        enabled_events:
          type: array
          items:
            type: string
            enum:
            - '*'
            - 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:
          type: string
          maxLength: 200
        status:
          type: string
          enum:
          - enabled
          - disabled
          description: Turn the endpoint off, or back on after it was turned off.
        metadata:
          type: object
          additionalProperties:
            type: string
    WebhookDeliveryResponseObject:
      type: object
      properties:
        status:
          type:
          - number
          - 'null'
        body:
          type:
          - string
          - 'null'
          description: The first 4,096 characters.
      required:
      - status
      - body
    ErrorEnvelope:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      required:
      - error
    WebhookEndpointList:
      type: object
      properties:
        object:
          type: string
          enum:
          - list
        data:
          type: array
          items:
            $ref: '#/components/schemas/WebhookEndpointObject'
        has_more:
          type: boolean
          description: Whether another page follows.
        next_cursor:
          type:
          - string
          - 'null'
          description: Pass as `starting_after` (or `cursor` for search) to get the next page.
      required:
      - object
      - data
      - has_more
      - next_cursor
    WebhookDeliveryObject:
      type: object
      properties:
        object:
          type: string
          enum:
          - webhook_delivery
        id:
          type: string
          example: whd_034XtPDs7UJ0TXzTsdaHZa
        endpoint:
          type: string
        event:
          type: string
        event_type:
          type: string
        replay_of:
          type:
          - string
          - 'null'
          description: The delivery this one replays.
        status:
          type: string
          enum:
          - pending
          - succeeded
          - failed
        attempts:
          type: number
        attempt_log:
          type: array
          items:
            $ref: '#/components/schemas/DeliveryAttemptObject'
        next_attempt_at:
          type:
          - string
          - 'null'
          format: date-time
        request:
          $ref: '#/components/schemas/WebhookDeliveryRequestObject'
        response:
          $ref: '#/components/schemas/WebhookDeliveryResponseObject'
        error:
          type:
          - string
          - 'null'
          description: Why the last attempt failed.
        created_at:
          type: string
          format: date-time
        completed_at:
          type:
          - string
          - 'null'
          format: date-time
      required:
      - object
      - id
      - endpoint
      - event
      - event_type
      - replay_of
      - status
      - attempts
      - attempt_log
      - next_attempt_at
      - request
      - response
      - error
      - created_at
      - completed_at
    WebhookEndpointObject:
      type: object
      properties:
        object:
          type: string
          enum:
          - webhook_endpoint
        id:
          type: string
          example: whe_034XtPDs7UJ0TXzTsdaHZa
        url:
          type: string
        description:
          type:
          - string
          - 'null'
        enabled_events:
          type: array
          items:
            type: string
        status:
          type: string
          enum:
          - enabled
          - disabled
        disabled_reason:
          type:
          - string
          - 'null'
          description: Why it was turned off, when MarketSDK turned it off.
        failing_since:
          type:
          - string
          - 'null'
          format: date-time
          description: Every delivery has failed since this time.
        last_success_at:
          type:
          - string
          - 'null'
          format: date-time
        secret:
          type: string
          description: The signing secret. Returned only when the endpoint is created or its secret rotated.
        metadata:
          type: object
          additionalProperties:
            type: string
        created_at:
          type: string
          format: date-time
      required:
      - object
      - id
      - url
      - description
      - enabled_events
      - status
      - disabled_reason
      - failing_since
      - last_success_at
      - metadata
      - created_at
    EventList:
      type: object
      properties:
        object:
          type: string
          enum:
          - list
        data:
          type: array
          items:
            $ref: '#/components/schemas/EventObject'
        has_more:
          type: boolean
          description: Whether another page follows.
        next_cursor:
          type:
          - string
          - 'null'
          description: Pass as `starting_after` (or `cursor` for search) to get the next page.
      required:
      - object
      - data
      - has_more
      - next_cursor
    EventObject:
      type: object
      properties:
        object:
          type: string
          enum:
          - event
        id:
          type: string
          example: evt_034XtPDs7UJ0TXzTsdaHZa
        type:
          type: string
          enum:
          - 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_version:
          type: string
          description: Always v1 in this version of the API.
        created:
          type: string
          format: date-time
        livemode:
          type: boolean
        data:
          type: object
          additionalProperties: true
          description: '`data.object` is the object as it was right after the change.'
      required:
      - object
      - id
      - type
      - api_version
      - created
      - livemode
      - data
    CreateWebhookEndpointDto:
      type: object
      properties:
        url:
          type: string
          description: An HTTPS URL on the public internet.
          example: https://shop.example/marketsdk/webhooks
        enabled_events:
          type: array
          description: Event types to send, or `*` for all.
          items:
            type: string
            enum:
            - '*'
            - 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:
          type: string
          maxLength: 200
        metadata:
          type: object
          additionalProperties:
            type: string
      required:
      - url
      - enabled_events
    DeliveryAttemptObject:
      type: object
      properties:
        at:
          type: string
          format: date-time
        status:
          type:
          - number
          - 'null'
          description: The HTTP status your endpoint answered with, or null if it did not answer.
        duration_ms:
          type: number
        error:
          type:
          - string
          - 'null'
      required:
      - at
      - status
      - duration_ms
      - error
    WebhookDeliveryList:
      type: object
      properties:
        object:
          type: string
          enum:
          - list
        data:
          type: array
          items:
            $ref: '#/components/schemas/WebhookDeliveryObject'
        has_more:
          type: boolean
          description: Whether another page follows.
        next_cursor:
          type:
          - string
          - 'null'
          description: Pass as `starting_after` (or `cursor` for search) to get the next page.
      required:
      - object
      - data
      - has_more
      - next_cursor
    DeletedWebhookEndpointObject:
      type: object
      properties:
        object:
          type: string
          enum:
          - webhook_endpoint
        id:
          type: string
        deleted:
          type: boolean
          enum:
          - true
      required:
      - object
      - id
      - deleted
    ErrorBody:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable. Never changes once published.
          example: resource_missing
        message:
          type: string
          description: For people.
          example: No seller has that id.
        param:
          type: string
          description: The request field at fault.
          example: seller
        request_id:
          type: string
          example: req_7Gq0mR2s9xVbN4kT1pLc
      required:
      - code
      - message
      - request_id
    WebhookDeliveryRequestObject:
      type: object
      properties:
        headers:
          type: object
          additionalProperties:
            type: string
        body:
          type: string
          description: The exact body sent.
      required:
      - headers
      - body
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: API key
      type: http
      description: 'An API key: msk_test_sk_…, msk_live_sk_…, or a publishable msk_…_pk_… key where allowed.'
x-refined-from:
- marketsdk-openapi.json
- marketsdk-openapi.json
x-stripe-permissions:
- permission: accounts
  category: Core
  resource: Accounts
  level: Write
  used_for: Create sellers' connected accounts and read their status
- permission: account_links
  category: Connect
  resource: Account Links
  level: Write
  used_for: Onboarding links for sellers
- permission: transfers
  category: Connect
  resource: Transfers
  level: Write
  used_for: Release funds to a seller, and reverse them on a refund


# --- truncated at 32 KB (32 KB total) ---
# Full source: https://artifacts.apis.io/marketsdk/openapi/marketsdk-webhooks-api-openapi.yml