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}