Whitespace Platform Activity Queues

asyncapi: 3.0.0
info:
  title: Whitespace Platform Activity Queues
  version: '3.1'
  description: |
    An AsyncAPI description of the Whitespace Platform event surface, generated by API Evangelist
    from Whitespace's own published queue guides. Whitespace does NOT publish an AsyncAPI document
    and does not offer HTTP webhooks — its event mechanism is a per-client Microsoft Azure Service
    Bus queue.

    Every significant user action on the platform creates a JSON activity document (`RWActivity`,
    optionally `RWCustomActivity`, and `RWComment` where the integration requires chat). That
    document is placed on the client organisation's queue, time-stamped, and served in strict
    first-in-first-out order. The message carries no sensitive contract data: it carries the
    activity string, the document reference and the message id, which the consumer then passes
    back into the REST API (`GET /api/risks/root/{rootID}`, `GET /api/activities/{rootID}/full`,
    `GET /api/documents/getLineGuidanceForRoot/{rootID}`, ...) to retrieve the full detail.

    Queues are provisioned per client, and optionally per team, by Whitespace Support, which
    supplies the queue name, key and connection string. Delivery is at-least-once by default
    (lock, process, settle; unsettled messages are unlocked and returned to the head of the
    queue); at-most-once is available on request. Messages never expire and each queue holds more
    than a quarter of a million messages. Pull-based delivery supports up to 100 simultaneous
    connections, and Azure's push APIs are unlimited. Duplicate detection, peek, and a dead-letter
    drop for poison messages are all part of the Service Bus layer.

    NOT AN OFFICIAL WHITESPACE ARTIFACT. Channel addressing, the message schema and the complete
    activity-string enumeration below are transcribed from "Integrating with Whitespace via Queues"
    v3.1 (7 March 2025, platform 3.1) and "Queues and the Whitespace Platform" v1.2.2. Nothing here
    is invented; anything the guides do not state is left out.
  contact:
    name: Whitespace Integration Team
    email: support@whitespace.co.uk
    url: https://apidocs.whitespace.co.uk/
  externalDocs:
    description: Integrating with Whitespace via Queues 3.1
    url: https://apidocs.whitespace.co.uk/Integrating_with_Whitespace_via_Queues_3.1.pdf
defaultContentType: application/json
servers:
  production:
    host: '{namespace}.servicebus.windows.net'
    protocol: amqp
    description: >-
      The client's Microsoft Azure Service Bus namespace for the Production platform. The
      namespace, queue name, key and connection string are supplied by Whitespace Support; they
      are not discoverable.
    variables:
      namespace:
        description: Azure Service Bus namespace issued by Whitespace Support.
        default: your-namespace
  sandbox:
    host: '{namespace}.servicebus.windows.net'
    protocol: amqp
    description: >-
      The equivalent Sandbox queue namespace. Sandbox queues are requested separately from
      support@whitespace.co.uk as step two of the three-step integration process.
    variables:
      namespace:
        description: Azure Service Bus namespace issued by Whitespace Support.
        default: your-sandbox-namespace
channels:
  clientActivityQueue:
    address: '{queueName}'
    title: Client activity queue
    description: >-
      The client organisation's Azure Service Bus queue. A client may run more than one queue —
      queues can be set up per team or per group of teams. By default only RWActivity documents
      (and RWCustomActivity, where the user has activated it) are placed on the queue; RWComment
      documents can be added when the integration needs chat messages.
    parameters:
      queueName:
        description: Queue name supplied by Whitespace Support alongside the key and connection string.
    messages:
      activity:
        $ref: '#/components/messages/RWActivity'
      customActivity:
        $ref: '#/components/messages/RWCustomActivity'
      comment:
        $ref: '#/components/messages/RWComment'
operations:
  receiveActivity:
    action: receive
    channel:
      $ref: '#/channels/clientActivityQueue'
    title: Consume platform activity messages
    description: >-
      Poll or stream the queue for the oldest message, process it according to
      body.hardcodedActivity, then settle it so the queue deletes it. If the consumer crashes or
      times out the message is unlocked and returned to the head of the queue (at-least-once).
      Exactly-once is achieved by logging processed message ids and screening incoming messages
      against that log.
    messages:
    - $ref: '#/channels/clientActivityQueue/messages/activity'
    - $ref: '#/channels/clientActivityQueue/messages/customActivity'
    - $ref: '#/channels/clientActivityQueue/messages/comment'
components:
  messages:
    RWActivity:
      name: RWActivity
      title: Platform activity document
      summary: The activity document generated by a significant user action on the Whitespace Platform.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/RWActivity'
    RWCustomActivity:
      name: RWCustomActivity
      title: Custom activity document
      summary: >-
        Structurally the same as RWActivity, but generated by user-defined custom actions — for
        example triggering an integration-side consumer process to call a third-party rating
        service. Only present when the user has activated custom activities.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/RWActivity'
    RWComment:
      name: RWComment
      title: Comment document
      summary: >-
        A simple log of a text comment involving users associated with this queue. Only placed on
        the queue when the integration asks for comments to be included.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/RWComment'
  schemas:
    RWActivity:
      type: object
      description: >-
        Activity documents are generated by all actions and are therefore variable in specific
        form; the keys below are those the guide identifies. The most salient are _id, createdAt,
        hardcodedActivity, parentDocID and userID.
      required:
      - _id
      - type
      - createdAt
      - hardcodedActivity
      - userID
      properties:
        _id:
          type: string
          description: >-
            Unique message/document reference. The first 38 characters are the root risk ID; the
            remainder identifies the contract instance and the activity document.
          example: ICBC2647B7-778F-49D3-84AC-316F8C297ACB::FO::ACTI::54309426-C8CF-4027-8EFE-060CE31EF902
        _rev:
          type: string
          description: Couchbase revision of the document.
          example: 1-0b1572b355539ebac561d37b8797ab7d
        type:
          type: string
          description: Document type discriminator.
          enum:
          - RWActivity
          - RWCustomActivity
          example: RWActivity
        activity:
          type: string
          description: >-
            The live description of the action, which sometimes extends hardcodedActivity to be
            more explicit.
          example: Requested a Line
        hardcodedActivity:
          type: string
          description: >-
            The activity string identifying the precise action that generated this document. This
            is the key a consumer switches on. The enumeration is Whitespace's complete published
            list as of platform 3.1; custom user-defined activity strings are also possible.
          example: Requested a Line
          enum:
          - A Line Was Removed
          - A Subjectivity Was Removed
          - Accepted a Quote
          - Accepted Endorsement
          - Added an Attachment
          - Added an Attachment from a Subjectivity Response
          - Attachment deleted
          - Attachment(s) shown
          - Bindable Line Written
          - Bindable Quote Not Taken Up
          - Bindable Quote Shown
          - Bound notify party
          - Broker Attempted To Satisfy A Subjectivity
          - Broking Partner Request
          - Changed or Added a Line item
          - Changed or Added Quote Details
          - Cloned a Quote
          - Cloned Endorsement
          - Cloned From Declaration
          - Cloned From Risk
          - Cloned From Template
          - Completed Endorsement
          - Contract Correction Approved
          - Contract Correction Completed
          - Contract Correction Declined
          - Contract Correction Deleted
          - Contract Correction Revoked
          - Contract Correction Shown
          - Contract Correction Withdrawn
          - Created Bindable Quote
          - Created New Draft
          - Created New Endorsement
          - Declaration shown to Facility
          - Declined Bindable Quote
          - Declined Endorsement
          - Declined Firm Order
          - Declined Quote Request
          - Deleted contract sections
          - Draft was Deleted
          - Endorsement was Deleted
          - Internal Broker Notes Edited
          - 'Internal Review: Contract Approved'
          - 'Internal Review: Contract Rejected'
          - 'Internal Review: Request Withdrawn'
          - 'Internal Review: Requested'
          - 'Internal Review: Self-Approved'
          - Library IDs Associated with Line Items
          - Line Conditions/Subjectivities were updated
          - Line Percentage Was Revised
          - Line Reference Was Revised
          - Line Removal Accepted
          - Line Removal Rejected
          - Line Removal Request
          - Line Removed
          - Line Written
          - Marked as Firm Order
          - Marked Facility Active
          - Marked Facility Expired
          - Marked Facility Inactive
          - Marketed Risk
          - Mid-Term Participant Change Completed
          - Off-Platform Bindable Line Written
          - Off-Platform line was adjusted
          - Off-Platform Line Written
          - Proposed a new Written Line Percentage
          - Questionnaire Answers Updated
          - Questionnaire Removed
          - Questionnaire Structure Updated
          - Quote Being Prepared was Deleted
          - Quote in Preparation
          - Quote Not Taken Up
          - Quote Requested
          - Quote was forwarded as a Marketed risk
          - Quote was forwarded as a Request To Quote
          - Quoted
          - Quoted with Quote Details
          - Replaced an Attachment
          - Request Received from Unapproved Broker
          - Request to Quote cloned to a Draft
          - Requested a Line
          - Re-Signed Line(s)
          - Responded to Subjectivity Response
          - Responded to Unapproved Broker
          - Returned to Broking Partner
          - Section Assigned to Shown Contract
          - Sent New Quote Request
          - Shared Endorsement
          - Shared Facility
          - Showed Endorsement
          - Showed Marketed Risk for Quote
          - Showed to Following Market
          - Signed Contract reverted to Firm Order
          - Signed Lines
          - Stamp Update Accepted
          - Stamp Update Rejected
          - Stamp Update Submitted
          - Subjectivities/Line Conditions Accepted
          - Subjectivities/Line Conditions Rejected
          - Template Applied
          - Template Visibility
          - Vertical Terms Updated
          - Viewed Attachment
          - Withdrew Bindable Quote
          - Withdrew Endorsement
          - Withdrew Firm Order
          - Withdrew Quote
          - Withdrew Quote Request
          - Wrote No Cover Given Line
        parentDocID:
          type: string
          description: The contract instance the activity belongs to (root ID plus stage segment).
          example: ICBC2647B7-778F-49D3-84AC-316F8C297ACB::FO
        linkedArchiveID:
          type: string
          description: The archive document written alongside this activity.
          example: ICBC2647B7-778F-49D3-84AC-316F8C297ACB::FO::ARCH::27287664-6DFE-4F1F-AA62-1FEBD2C40173
        createdAt:
          type: string
          description: 'Time stamp in "YYYY-MM-DD HH:MM:SS" form.'
          example: '2022-05-25 11:16:46'
        userID:
          type: string
          description: The platform user whose action generated the document.
          example: MUD38EC011-780A-42D3-94DA-FD9063F5DAF9
        channels:
          type: array
          description: Couchbase channels (companyid_TEAMID) that may see the document.
          items:
            type: string
            example: palermo_ALL
        apnsData:
          type: object
          description: Notification/email generation block.
          properties:
            title:
              type: string
              example: Requested a Line
            subtitle:
              type: string
              example: AJC Broking Ltd
            subscriptionRootID:
              type: string
              example: ICBC2647B7-778F-49D3-84AC-316F8C297ACB
            channels:
              type: array
              items:
                type: string
            data:
              type: object
              properties:
                docId:
                  type: string
            dataForEmail:
              type: object
              properties:
                riskInformation:
                  type: array
                  items:
                    type: string
                userID:
                  type: string
        provenance:
          type: object
          description: Write audit block present on platform documents.
          properties:
            dataHash:
              type: string
            provHash:
              type: string
            system:
              type: string
              example: LaVAPI
            userID:
              type: string
            version:
              type: string
              example: '2022-05-24@19:08:46'
            writtenAt:
              type: string
              example: '2022-05-25 11:16:46'
      examples:
      - name: requestedALine
        summary: A broker placed a firm order for a written line (truncated sample from the guide).
        value:
          _id: ICBC2647B7-778F-49D3-84AC-316F8C297ACB::FO::ACTI::54309426-C8CF-4027-8EFE-060CE31EF902
          _rev: 1-0b1572b355539ebac561d37b8797ab7d
          activity: Requested a Line
          hardcodedActivity: Requested a Line
          parentDocID: ICBC2647B7-778F-49D3-84AC-316F8C297ACB::FO
          linkedArchiveID: ICBC2647B7-778F-49D3-84AC-316F8C297ACB::FO::ARCH::27287664-6DFE-4F1F-AA62-1FEBD2C40173
          createdAt: '2022-05-25 11:16:46'
          type: RWActivity
          userID: MUD38EC011-780A-42D3-94DA-FD9063F5DAF9
          channels:
          - palermo_ALL
          - ajc_PROPERTYAFRICA
    RWComment:
      type: object
      description: A chat comment between teams on a risk, as described in the platform OpenAPI.
      properties:
        _id:
          type: string
        _rev:
          type: string
        type:
          type: string
          enum:
          - RWComment
        associatedRootID:
          type: string
        comment:
          type: string
        user:
          type: string
        isInternal:
          type: boolean
        createdAt:
          type: string
        updatedAt:
          type: string
        channels:
          type: array
          items:
            type: string
x-apievangelist:
  generated: '2026-07-25'
  method: generated
  provider_publishes_asyncapi: false
  provider_publishes_webhooks: false
  sources:
  - https://apidocs.whitespace.co.uk/Integrating_with_Whitespace_via_Queues_3.1.pdf
  - https://apidocs.whitespace.co.uk/Queues_and_the_Whitespace_Platform_v1.2.2.pdf
  - openapi/whitespace-london-platform-openapi.yml
  delivery:
    guarantee: at-least-once (settlement); at-most-once available on request
    ordering: strict FIFO, oldest first
    retention: indefinite — no expiry timer
    capacity: more than 250,000 messages per queue
    concurrency: up to 100 simultaneous pull connections; unlimited via Azure push APIs
    duplicate_detection: true
    peek: true
    dead_letter: true
  provisioning: >-
    Queues are created by Whitespace Support per organisation, and optionally per team; the queue
    name, key and connection string are issued out of band.
  reserved_activity_strings:
    note: >-
      Listed in the guide as "not currently implemented, but which we envision a future use for".
      Excluded from the enum above. Note that "Created New Placement" nonetheless appears as an
      example activity value in the platform OpenAPI.
    values:
    - Accepted a Quote Request
    - Accepted on behalf of Buyer
    - Change rejected (Conflict)
    - Contract Published Succesfully
    - Contract Updated
    - Created New Placement
    - Endorsement Not Taken Up
    - Offered Quote
    - Placing Updated
    - Risk Has Been Deleted
    - Sent to Broker
    - Viewed
  rest_callbacks:
    note: The API calls a consumer typically makes after receiving a message.
    operations:
    - GET /api/risks/root/{rootID}
    - GET /api/activities/{rootID}/full
    - GET /api/documents/getLineGuidanceForRoot/{rootID}
    - GET /api/risks/{riskID}/getExtendedMRC
    - POST /export/pdf/{riskID}