Mindbody Webhooks API

openapi: 3.0.3
info:
  title: Mindbody Webhooks API
  version: '1.0'
  description: Subscription and delivery platform that pushes near real-time event notifications for sites, locations, appointments, classes, clients, sales, and staff. Partners create and manage 
    subscriptions over a REST control plane, and Mindbody pushes JSON events to the registered webhook URL with HMAC-SHA256 signature verification. Authentication uses an API-Key header issued via the
    Mindbody webhooks developer portal.
  contact:
    name: Mindbody API Support
    url: https://support.mindbodyonline.com/s/contactapisupport
  license:
    name: Proprietary
  x-generated-from: Mindbody-API-SDKs python SDK
  x-last-validated: '2026-05-28'
servers:
- url: https://push-api.mindbodyonline.com
  description: Production
tags:
- name: Metrics
  description: Metrics operations.
- name: Subscriptions
  description: Subscriptions operations.
paths:
  /api/v1/metrics:
    get:
      tags:
      - Metrics
      summary: Mindbody This Endpoint Gets Metrics for All the Subscriptions Associated with
      description: This endpoint gets metrics for all the subscriptions associated with your Public API developer account.
      operationId: getMetrics
      parameters: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMetricsResponse'
              examples:
                Getmetrics200Example:
                  summary: Default getMetrics 200 example
                  x-microcks-default: true
                  value:
                    items: &id003
                    - {}
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      security:
      - ApiKeyAuth: []
  /api/v1/subscriptions:
    get:
      tags:
      - Subscriptions
      summary: Mindbody This Endpoint Searches for Subscriptions Associated with Your
      description: 'This endpoint searches for subscriptions associated with your developer portal account: You can retrieve a specific subscription by calling GET(by ID).'
      operationId: getSubscriptions
      parameters: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PushApiResultGetSubscriptionsResponse'
              examples:
                Getsubscriptions200Example:
                  summary: Default getSubscriptions 200 example
                  x-microcks-default: true
                  value:
                    errorInformation: &id007
                    - {}
                    isSuccess: true
                    value: {}
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      security:
      - ApiKeyAuth: []
    post:
      tags:
      - Subscriptions
      summary: Mindbody This Endpoint Creates a Pending Subscription That is Linked to Your
      description: This endpoint creates a pending subscription that is linked to your developer portal account. After you have created a subscription, you can activate it using the PATCH Subscription
        endpoint.
      operationId: createSubscription
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSubscriptionRequest'
            examples:
              CreatesubscriptionRequestExample:
                summary: Default createSubscription request example
                x-microcks-default: true
                value:
                  eventIds: &id002
                  - example-value
                  eventSchemaVersion: 1.0
                  referenceId: example-value
                  webhookUrl: https://example.mindbodyonline.com/resource/abc123
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PushApiResultCreateSubscriptionResponse'
              examples:
                Createsubscription200Example:
                  summary: Default createSubscription 200 example
                  x-microcks-default: true
                  value:
                    errorInformation: &id005
                    - {}
                    isSuccess: true
                    value: {}
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      security:
      - ApiKeyAuth: []
  /api/v1/subscriptions/{subscriptionId}:
    delete:
      tags:
      - Subscriptions
      summary: Mindbody This Endpoint Deactivates a Subscription Associated with the Passed ID
      description: This endpoint deactivates a subscription associated with the passed ID.
      operationId: deleteSubscription
      parameters:
      - name: subscriptionId
        in: path
        required: true
        description: The subscription ID (a GUID) that you are deactivating.
        schema:
          type: string
        example: example-value
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PushApiResultDeactivateSubscriptionResponse'
              examples:
                Deletesubscription200Example:
                  summary: Default deleteSubscription 200 example
                  x-microcks-default: true
                  value:
                    errorInformation: &id006
                    - {}
                    isSuccess: true
                    value: {}
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      security:
      - ApiKeyAuth: []
    get:
      tags:
      - Subscriptions
      summary: Mindbody This Endpoint Finds and Returns the Single Subscription Associated
      description: This endpoint finds and returns the single subscription associated with the passed ID.
      operationId: getSubscription
      parameters:
      - name: subscriptionId
        in: path
        required: true
        description: Returns the single location identified by this ID (a GUID).
        schema:
          type: string
        example: example-value
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PushApiResultSubscription'
              examples:
                Getsubscription200Example:
                  summary: Default getSubscription 200 example
                  x-microcks-default: true
                  value:
                    errorInformation: &id001
                    - {}
                    isSuccess: true
                    value: {}
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      security:
      - ApiKeyAuth: []
    patch:
      tags:
      - Subscriptions
      summary: Mindbody This Endpoint Can Activate a New Subscription or Reactivate an
      description: "This endpoint can activate a new subscription or reactivate an inactive subscription that is associated with your developer portal account, by updating the status. You can also update
        your subscription’s eventIds, eventSchemaVersion, referenceId, and webhookUrl."
      operationId: patchSubscription
      parameters:
      - name: subscriptionId
        in: path
        required: true
        description: "The subscription’s ID (a GUID)."
        schema:
          type: string
        example: example-value
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchSubscriptionRequest'
            examples:
              PatchsubscriptionRequestExample:
                summary: Default patchSubscription request example
                x-microcks-default: true
                value:
                  eventIds: &id004
                  - example-value
                  eventSchemaVersion: 1.0
                  referenceId: example-value
                  status: example-value
                  webhookUrl: https://example.mindbodyonline.com/resource/abc123
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PushApiResultSubscription'
              examples:
                Patchsubscription200Example:
                  summary: Default patchSubscription 200 example
                  x-microcks-default: true
                  value:
                    errorInformation: *id001
                    isSuccess: true
                    value: {}
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      security:
      - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: API-Key
      description: Mindbody-issued API key (server-to-server). Required on every request.
  schemas:
    CreateSubscriptionRequest:
      type: object
      description: Implementation of the 'CreateSubscriptionRequest' model. Request used to add a webhook subscription for the requesting developer
      properties:
        eventIds:
          type: array
          items:
            type: string
          description: The events you want to be sent to the specified `webhookUrl`.
          example: *id002
        eventSchemaVersion:
          type: number
          format: double
          description: The event schema version for this subscription. `1` is currently the only accepted value.
          example: 1.0
        referenceId:
          type: string
          description: An arbitrary field that you can set to a value of your choice. Mindbody stores and returns this value for the subscription you are creating. Most commonly, this field stores a 
            GUID that you can use in your application.
          example: example-value
        webhookUrl:
          type: string
          description: The URL that Mindbody posts the event notifications to. Webhook URL Requirements lists considerations and requirements for this URL.
          example: https://example.mindbodyonline.com/resource/abc123
    CreateSubscriptionResponse:
      type: object
      description: Implementation of the 'CreateSubscriptionResponse' model. The created subscription
      properties:
        eventIds:
          type: array
          items:
            type: string
          description: The events that are to be sent to this subscription's `webhookUrl`.
          example:
          - example-value
        eventSchemaVersion:
          type: number
          format: double
          description: The event schema version associated with the subscription. Currently, this is always `1`.
          example: 1.0
        messageSignatureKey:
          type: string
          description: The subscription security key that you can use to verify an event payload's authenticity. It is important that you store this value because this is the only endpoint that 
            returns it See X-Mindbody Signature Header for more details.
          example: example-value
        referenceId:
          type: string
          description: An arbitrary ID that can be specified in the POST Subscription request body, and is saved for the requesting developer's use.
          example: example-value
        status:
          type: string
          description: "The subscription's current status. *Possible Values:* 1. `PendingActivation` - The subscription is created but not receiving event notifications. To start receiving event notifications,
            set the subscription’s status to `Active` using the PATCH Subscription endpoint. 2. `Active` - The subscription is active and can receive event notifications. 3. `DeactivatedByUser` - You deactivated
            the subscription. 4. `DeactivatedByAdmin` - Mindbody deactivated your subscription. 5. `DeactivatedTooManyFailedMe"
          example: example-value
        statusChangeDate:
          type: string
          format: date-time
          description: The UTC date and time when the subscription's status was last updated.
          example: '2026-05-28T14:30:00Z'
        statusChangeMessage:
          type: string
          description: A message generated by Mindbody that explains why a subscription's status changed.
          example: example-value
        statusChangeUser:
          type: string
          description: The first name of the developer or Mindbody staff member who changed the subscription's status.
          example: example-value
        subscriptionCreationDateTime:
          type: string
          format: date-time
          description: The UTC date and time when the subscription was created.
          example: '2026-05-28T14:30:00Z'
        subscriptionId:
          type: string
          description: The subscription's ID (a GUID).
          example: example-value
        webhookUrl:
          type: string
          description: The webhook to which the listed `eventIds` are sent.
          example: https://example.mindbodyonline.com/resource/abc123
    DeactivateSubscriptionResponse:
      type: object
      description: Implementation of the 'DeactivateSubscriptionResponse' model. Returned after a subscription is deactivated
      properties:
        deactivationDateTime:
          type: string
          format: date-time
          description: The UTC date and time when the deactivation took place.
          example: '2026-05-28T14:30:00Z'
        message:
          type: string
          description: A message about the deactivation request. Unless an error occurs, this message always `"Subscription deactivated successfully."`.
          example: example-value
        referenceId:
          type: string
          description: The subscription's reference ID, assigned when the subscription was created.
          example: example-value
        subscriptionId:
          type: string
          description: The subscription ID (a GUID).
          example: example-value
    GetMetricsResponse:
      type: object
      description: Implementation of the 'GetMetricsResponse' model. A wrapper for returning subscription metrics to API users
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Metric'
          description: Contains the metrics for the passed subscription
          example: *id003
    GetSubscriptionsResponse:
      type: object
      description: Implementation of the 'GetSubscriptionsResponse' model. A wrapper for a get subscriptions request
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Subscription'
          description: A list of subscriptions
          example:
          - {}
    Metric:
      type: object
      description: Implementation of the 'Metric' model. Metrics for subscription
      properties:
        creationDateTime:
          type: string
          format: date-time
          description: The UTC date and time when the subscription was created.
          example: '2026-05-28T14:30:00Z'
        messagesAttempted:
          type: integer
          format: int32
          description: The number of event notifications Mindbody attempted to deliver to the subscription `webhookUrl`, including retries.
          example: 1
        messagesDelivered:
          type: integer
          format: int32
          description: The number of event notifications Mindbody successfully delivered to the subscription `webhookUrl`.
          example: 1
        messagesFailed:
          type: integer
          format: int32
          description: The number of event notifications that Mindbody stopped trying to send after 3 hours.
          example: 1
        messagesUndelivered:
          type: integer
          format: int32
          description: The number of event notifications where MINDBODY received a failure response from the subscription `webhookUrl`.
          example: 1
        status:
          type: string
          description: "The subscription's current status. **Possible Values**:<br /> `PendingActivation` - The subscription is created but not receiving event notifications.To start receiving event notifications,
            set the subscription’s status to Active using the PATCH Subscription endpoint.<br /> `Active` - The subscription is active and can receive event notifications.<br /> `DeactivatedByUser` - You
            deactivated the subscription.<br /> `DeactivatedByAdmin` - Mindbody deactivated your subscription.<br /> `DeactivatedT"
          example: example-value
        statusChangeDate:
          type: string
          format: date-time
          description: The UTC date and time when the subscription `status` was last updated.
          example: '2026-05-28T14:30:00Z'
        subscriptionId:
          type: string
          description: The subscription's ID (a GUID).
          example: example-value
    PatchSubscriptionRequest:
      type: object
      description: Implementation of the 'PatchSubscriptionRequest' model. A request to patch update a subscription
      properties:
        eventIds:
          type: array
          items:
            type: string
          description: A list of event IDs that you want to update or subscribe to.
          example: *id004
        eventSchemaVersion:
          type: number
          format: double
          description: The event schema version associated with the subscription. Currently, this is always `1`.
          example: 1.0
        referenceId:
          type: string
          description: An arbitrary field that you can set to a value of your choice. Mindbody stores and returns this value for the subscription you are activating. Most commonly, this field stores a
            GUID that you can use in your application.
          example: example-value
        status:
          type: string
          description: "The subscription’s current status, as of the last update."
          example: example-value
        webhookUrl:
          type: string
          description: The URL registered as the target of the webhook deliveries. Mindbody posts the event notifications to this URL. Webhook URL Requirements lists considerations and requirements 
            for this URL.
          example: https://example.mindbodyonline.com/resource/abc123
    PushApiError:
      type: object
      description: Implementation of the 'PushApiError' model. An error returned by the push API for application errors
      properties:
        errorCode:
          type: integer
          format: int32
          description: A unique ID for the returned error code
          example: 1
        errorMessage:
          type: string
          description: A message indicating what went wrong
          example: example-value
        errorType:
          type: string
          description: A category/type associated with the error
          example: example-value
    PushApiResultCreateSubscriptionResponse:
      type: object
      description: Implementation of the 'PushApiResult[CreateSubscriptionResponse]' model. A result returned for every request to the push API
      properties:
        errorInformation:
          type: array
          items:
            $ref: '#/components/schemas/PushApiError'
          description: The model property of type List[PushApiError].
          example: *id005
        isSuccess:
          type: boolean
          description: The model property of type bool.
          example: true
        value:
          $ref: '#/components/schemas/CreateSubscriptionResponse'
          description: The created subscription
    PushApiResultDeactivateSubscriptionResponse:
      type: object
      description: Implementation of the 'PushApiResult[DeactivateSubscriptionResponse]' model. A result returned for every request to the push API
      properties:
        errorInformation:
          type: array
          items:
            $ref: '#/components/schemas/PushApiError'
          description: The model property of type List[PushApiError].
          example: *id006
        isSuccess:
          type: boolean
          description: The model property of type bool.
          example: true
        value:
          $ref: '#/components/schemas/DeactivateSubscriptionResponse'
          description: Returned after a subscription is deactivated
    PushApiResultGetSubscriptionsResponse:
      type: object
      description: Implementation of the 'PushApiResult[GetSubscriptionsResponse]' model. A result returned for every request to the push API
      properties:
        errorInformation:
          type: array
          items:
            $ref: '#/components/schemas/PushApiError'
          description: The model property of type List[PushApiError].
          example: *id007
        isSuccess:
          type: boolean
          description: The model property of type bool.
          example: true
        value:
          $ref: '#/components/schemas/GetSubscriptionsResponse'
          description: A wrapper for a get subscriptions request
    PushApiResultSubscription:
      type: object
      description: Implementation of the 'PushApiResult[Subscription]' model. A result returned for every request to the push API
      properties:
        errorInformation:
          type: array
          items:
            $ref: '#/components/schemas/PushApiError'
          description: The model property of type List[PushApiError].
          example: *id001
        isSuccess:
          type: boolean
          description: The model property of type bool.
          example: true
        value:
          $ref: '#/components/schemas/Subscription'
          description: A webhook subscription
    Subscription:
      type: object
      description: Implementation of the 'Subscription' model. A webhook subscription
      properties:
        eventIds:
          type: array
          items:
            type: string
          description: The events that are to be sent to this subscription's `webhookUrl`.
          example:
          - example-value
        eventSchemaVersion:
          type: number
          format: double
          description: The event schema version associated with the subscription. Currently, this is always `1`.
          example: 1.0
        referenceId:
          type: string
          description: An arbitrary ID that can be specified in the POST Subscription request body, and is saved for the requesting developer's use.
          example: example-value
        status:
          type: string
          description: "The subscription's current status. *Possible Values:* 1. `PendingActivation` - The subscription is created but not receiving event notifications. To start receiving event notifications,
            set the subscription’s status to `Active` using the PATCH Subscription endpoint. 2. `Active` - The subscription is active and can receive event notifications. 3. `DeactivatedByUser` - You deactivated
            the subscription. 4. `DeactivatedByAdmin` - Mindbody deactivated your subscription. 5. `DeactivatedTooManyFailedMe"
          example: example-value
        statusChangeDate:
          type: string
          format: date-time
          description: The UTC date and time when the subscription's status was last updated.
          example: '2026-05-28T14:30:00Z'
        statusChangeMessage:
          type: string
          description: A message generated by Mindbody that explains why a subscription's status changed.
          example: example-value
        statusChangeUser:
          type: string
          description: The first name of the developer or Mindbody staff member who changed the subscription's status.
          example: example-value
        subscriptionCreationDateTime:
          type: string
          format: date-time
          description: The UTC date and time when the subscription was created.
          example: '2026-05-28T14:30:00Z'
        subscriptionId:
          type: string
          description: The subscription's ID (a GUID).
          example: example-value
        webhookUrl:
          type: string
          description: The webhook to which the listed `eventIds` are sent.
          example: https://example.mindbodyonline.com/resource/abc123
security:
- ApiKeyAuth: []