openapi: 3.0.0
info:
  title: Ascend StreamAPI Webhooks
  version: 188.0.0
  description: |
    StreamAPI real-time data change notifications are delivered over Amazon SNS
    (Simple Notification Service) webhooks.

    RabbitMQ support has been replaced with SNS webhooks and will end on 9/27/2026.
    All users should migrate to webhooks by that date. There is no public REST
    registration API: submit a support ticket with your HTTPS webhook URL.

    Your server must accept HTTP POST (JSON or text/plain), return 2xx quickly,
    and handle both SubscriptionConfirmation and Notification payloads. On first
    registration, AWS SNS sends a SubscriptionConfirmation; you must GET or POST
    the SubscribeURL or you will not receive events.

    Filter events with MessageAttributes.RoutingKey without parsing the full Message body.
    - Format: organizationId.locationId.Endpoint.operationType
    - Example: '66d22762060811049b50d085.*.AppointmentV1.*'

      - organizationId - The organization you have access to. `*` is NOT RECOMMENDED.
      - locationId - Split messages by location, or `*` for all locations.
      - Endpoint - Message type (for example, AppointmentV1). Must include the version suffix.
      - operationType - CREATE, UPDATE, DELETE, or `*` for all types.

     - ## '*.*.*.*' - NOT RECOMMENDED
          + #### This listens to ALL organizations you have access to and can overwhelm your webhook endpoint.

      #### WARNING: The routing key must be exact, with no typos, and cannot be missing its version (for example "V1") or you will not receive messages.

      #### Note: See the corresponding REST API endpoint if there is a question on what data the StreamAPI event pertains to.

    ## StreamingAPI Endpoint List
    - AppointmentColorV1
    - AppointmentV1
    - AppointmentHistoryV1
    - CarrierInsurancePlanCoordinationOfBenefitsV1
    - CarrierInsurancePlanV1
    - CarrierPlanCopayExceptionV1
    - CarrierPlanCoverageExceptionV1
    - CarrierPlanDeductibleV1
    - ClinicalNoteV1
    - ClinicalNoteTemplateUserFavoriteV1
    - ColorCategoryV1
    - CoverageProcedureCopayV1
    - CoverageProcedureRangeV1
    - DayNoteV1
    - DefaultPlanCoverageV1
    - DentalLabV1
    - DocumentV1
    - EventV1
    - ExamImageV1
    - ExamV1
    - FeeScheduleV1
    - FeeScheduleRangeV1
    - FeeScheduleRangeV2
    - InsuranceCarrierWithExcludedProcedureV1
    - InsuranceCarrierV1
    - InsuranceClaimV1
    - LocationClaimDefaultsV1
    - LocationV1
    - LocationHourV1
    - LocationPovertyLevelV1
    - MedicalAlertV1
    - MissedAppointmentV1
    - OperatoryV1
    - OrganizationLedgerRuleV1
    - OrganizationLedgerTypeV1
    - PatientBookingAvailabilityV1
    - PatientConditionV1
    - PatientInsurancePlanV1
    - PatientMedicalAlertV1
    - PatientNoteV1
    - PatientPaymentPlanV1
    - PatientPrescriptionV1
    - PatientProcedureV1
    - PatientRecareV1
    - PatientV1
    - PatientToothV1
    - PerioExamV1
    - PerioProbeV1
    - PracticeProcedureV1
    - PrescriptionDrugCategoryV1
    - PrescriptionDrugUnitV1
    - PrescriptionPrintSettingV1
    - PrescriptionTemplateV1
    - ProviderDaysExceptionV1
    - ProviderHourV1
    - ProviderV1
    - RecareTemplateV1
    - ScheduleTemplateAppointmentReasonV1
    - ScheduleTemplateV1
    - SubscriberInsurancePlanV1
    - TransactionV1
    - TransactionTagV1
    - TransferReasonV1
    - TxCaseV1
    - UserV1
    - VisitV1
paths: {}
components:
  schemas:
    SnsMessageAttribute:
      type: object
      description: AWS SNS message attribute (Type and Value).
      properties:
        Type:
          type: string
          example: String
        Value:
          type: string
          example: 5d111c20ca7b487854a79d0d.-1.OperatoryV1.UPDATE
    SnsMessageAttributes:
      type: object
      description: StreamAPI attributes on the SNS envelope. Use RoutingKey to filter events.
      properties:
        RoutingKey:
          $ref: '#/components/schemas/SnsMessageAttribute'
        organizationId:
          $ref: '#/components/schemas/SnsMessageAttribute'
        locationId:
          $ref: '#/components/schemas/SnsMessageAttribute'
        OrganizationId:
          $ref: '#/components/schemas/SnsMessageAttribute'
        MessageType:
          $ref: '#/components/schemas/SnsMessageAttribute'
    StreamApiDataChangeEvent:
      type: object
      description: Inner StreamAPI event. The SNS Message field is a stringified JSON object of this shape.
      properties:
        messageType:
          type: string
          example: DataChange
        applicationId:
          type: string
          example: hAnIzDLqlKBpPz2hscufe4HpuGmmkpl4
        clientName:
          type: string
          example: Developer
        type:
          type: string
          description: Entity type, including version suffix.
          example: OperatoryV1
        id:
          type: string
          example: '64000000000005'
        operation:
          type: string
          enum:
            - CREATE
            - UPDATE
            - DELETE
          example: UPDATE
        payload:
          type: object
          additionalProperties: true
          description: Entity payload (varies by type).
        transactionId:
          type: string
          example: 116c84a5-33ba-4d4c-b46c-3ebce5d506e0
        correlationId:
          type: string
          example: 116c84a5-33ba-4d4c-b46c-3ebce5d506e0
        sendTime:
          type: integer
          format: int64
          description: Epoch milliseconds when the event was sent.
          example: 1771371664352
    SnsWebhookEnvelope:
      type: object
      description: |
        AWS SNS POST body delivered to your HTTPS webhook. When Type is Notification,
        Message is a string containing a StreamApiDataChangeEvent JSON object.
      properties:
        Type:
          type: string
          enum:
            - Notification
            - SubscriptionConfirmation
            - UnsubscribeConfirmation
          example: Notification
        MessageId:
          type: string
          description: Unique ID for the message (use for idempotency).
          example: 1899eea0-81b3-5112-88dd-8cae7f6399b5
        TopicArn:
          type: string
          example: arn:aws:sns:us-east-1:393668382772:Org_5d111c20ca7b487854a79d0d
        Message:
          type: string
          description: For Notification, a stringified StreamApiDataChangeEvent JSON object.
        Timestamp:
          type: string
          format: date-time
          example: '2026-02-17T23:41:04.426Z'
        SignatureVersion:
          type: string
          example: '1'
        Signature:
          type: string
          description: Base64-encoded signature for verification.
        SigningCertURL:
          type: string
          format: uri
        UnsubscribeURL:
          type: string
          format: uri
        SubscribeURL:
          type: string
          format: uri
          description: Present on SubscriptionConfirmation. GET or POST this URL to confirm.
        Token:
          type: string
          description: Present on SubscriptionConfirmation.
        MessageAttributes:
          $ref: '#/components/schemas/SnsMessageAttributes'