asyncapi: 2.6.0 info: title: Upvest Investment Events description: >- The Upvest Investment API uses an asynchronous, event-driven architecture where events represent state changes within the system. Webhook subscriptions allow your application to receive real-time notifications about user onboarding, order lifecycle changes, portfolio rebalancing, payment processing, and other investment operations. Events are delivered via HTTPS POST requests with at-least-once delivery semantics, meaning your handler must be idempotent. version: '1.0.0' contact: name: Upvest Support url: https://upvest.co/ externalDocs: description: Upvest Webhooks Documentation url: https://docs.upvest.co/documentation/concepts/api_concepts/webhooks servers: production: url: '{webhookUrl}' protocol: https description: >- Your registered webhook endpoint. Must use HTTPS with TLS 1.2 or higher. The host must be a DNS name, not an IP address. variables: webhookUrl: description: >- The HTTPS URL registered as your webhook endpoint. security: - httpSignature: [] channels: /webhook: description: >- The webhook delivery channel. Upvest sends HTTPS POST requests to your registered endpoint containing one or more events. Events within a single request are ordered by created_at in ascending order. There are no ordering guarantees across separate requests. publish: operationId: receiveWebhookEvents summary: Receive webhook event notifications description: >- Receive one or more event notifications from the Upvest Investment API. Each request contains a payload array with event objects. Your handler should return a 2xx status code to acknowledge receipt. Events may be delivered more than once, so implement idempotent processing using the event id field. message: oneOf: - $ref: '#/components/messages/UserEvent' - $ref: '#/components/messages/UserCheckEvent' - $ref: '#/components/messages/AccountEvent' - $ref: '#/components/messages/AccountGroupEvent' - $ref: '#/components/messages/OrderEvent' - $ref: '#/components/messages/OrderCancellationEvent' - $ref: '#/components/messages/ExecutionEvent' - $ref: '#/components/messages/PositionEvent' - $ref: '#/components/messages/CashBalanceEvent' - $ref: '#/components/messages/PortfolioEvent' - $ref: '#/components/messages/RebalancingEvent' - $ref: '#/components/messages/SavingsPlanEvent' - $ref: '#/components/messages/DirectDebitEvent' - $ref: '#/components/messages/WithdrawalEvent' - $ref: '#/components/messages/MandateEvent' - $ref: '#/components/messages/SecuritiesTransferEvent' - $ref: '#/components/messages/AccountTransferEvent' - $ref: '#/components/messages/CorporateActionEvent' - $ref: '#/components/messages/LiquidationEvent' - $ref: '#/components/messages/ReportEvent' - $ref: '#/components/messages/FeeEvent' components: securitySchemes: httpSignature: type: httpApiKey name: Signature in: header description: >- Upvest signs webhook requests using HTTP message signatures. Your handler should verify the signature to ensure the request originated from Upvest and was not tampered with in transit. messages: UserEvent: name: UserEvent title: User Event summary: >- Events related to user lifecycle changes including creation, updates, and status transitions. contentType: application/json payload: $ref: '#/components/schemas/WebhookPayload' examples: - name: UserCreated payload: payload: - id: fbecea50-2f35-4969-96af-342271da9eca created_at: '2024-01-15T14:10:00.000Z' event_type: USER.CREATED object: id: 83d83ec2-d2ca-49ff-bbea-b92b5c3be202 type: USER webhook_id: 091915d8-7b4b-4d25-8208-f8e2d4b30070 UserCheckEvent: name: UserCheckEvent title: User Check Event summary: >- Events related to user compliance and verification check outcomes. contentType: application/json payload: $ref: '#/components/schemas/WebhookPayload' AccountEvent: name: AccountEvent title: Account Event summary: >- Events related to investment account lifecycle changes including opening, closing, and status updates. contentType: application/json payload: $ref: '#/components/schemas/WebhookPayload' AccountGroupEvent: name: AccountGroupEvent title: Account Group Event summary: >- Events related to account group changes. contentType: application/json payload: $ref: '#/components/schemas/WebhookPayload' OrderEvent: name: OrderEvent title: Order Event summary: >- Events related to the order lifecycle including placement, processing, filling, and rejection. Every order status change emits a webhook event. contentType: application/json payload: $ref: '#/components/schemas/WebhookPayload' OrderCancellationEvent: name: OrderCancellationEvent title: Order Cancellation Event summary: >- Events related to order cancellation requests and their outcomes. contentType: application/json payload: $ref: '#/components/schemas/WebhookPayload' ExecutionEvent: name: ExecutionEvent title: Execution Event summary: >- Events related to order execution fills. Every execution associated with an order has its own set of statuses, and every status change emits a webhook event. contentType: application/json payload: $ref: '#/components/schemas/WebhookPayload' PositionEvent: name: PositionEvent title: Position Event summary: >- Events related to changes in holdings and positions within accounts. contentType: application/json payload: $ref: '#/components/schemas/WebhookPayload' CashBalanceEvent: name: CashBalanceEvent title: Cash Balance Event summary: >- Events related to changes in account cash balances. contentType: application/json payload: $ref: '#/components/schemas/WebhookPayload' PortfolioEvent: name: PortfolioEvent title: Portfolio Event summary: >- Events related to portfolio creation, updates, and allocation changes. contentType: application/json payload: $ref: '#/components/schemas/WebhookPayload' RebalancingEvent: name: RebalancingEvent title: Rebalancing Event summary: >- Events related to portfolio rebalancing execution and completion. contentType: application/json payload: $ref: '#/components/schemas/WebhookPayload' SavingsPlanEvent: name: SavingsPlanEvent title: Savings Plan Event summary: >- Events related to savings plan creation, execution, and status changes. contentType: application/json payload: $ref: '#/components/schemas/WebhookPayload' DirectDebitEvent: name: DirectDebitEvent title: Direct Debit Event summary: >- Events related to direct debit funding operations and their status transitions. contentType: application/json payload: $ref: '#/components/schemas/WebhookPayload' WithdrawalEvent: name: WithdrawalEvent title: Withdrawal Event summary: >- Events related to cash withdrawal processing and completion. contentType: application/json payload: $ref: '#/components/schemas/WebhookPayload' MandateEvent: name: MandateEvent title: Mandate Event summary: >- Events related to direct debit mandate creation and revocation. contentType: application/json payload: $ref: '#/components/schemas/WebhookPayload' SecuritiesTransferEvent: name: SecuritiesTransferEvent title: Securities Transfer Event summary: >- Events related to inbound and outbound securities transfer operations. contentType: application/json payload: $ref: '#/components/schemas/WebhookPayload' AccountTransferEvent: name: AccountTransferEvent title: Account Transfer Event summary: >- Events related to account transfer operations between entities. contentType: application/json payload: $ref: '#/components/schemas/WebhookPayload' CorporateActionEvent: name: CorporateActionEvent title: Corporate Action Event summary: >- Events related to corporate actions on held securities such as dividends, splits, and mergers. contentType: application/json payload: $ref: '#/components/schemas/WebhookPayload' LiquidationEvent: name: LiquidationEvent title: Liquidation Event summary: >- Events related to account liquidation operations. contentType: application/json payload: $ref: '#/components/schemas/WebhookPayload' ReportEvent: name: ReportEvent title: Report Event summary: >- Events related to report generation completion. contentType: application/json payload: $ref: '#/components/schemas/WebhookPayload' FeeEvent: name: FeeEvent title: Fee Event summary: >- Events related to fee charges on accounts. contentType: application/json payload: $ref: '#/components/schemas/WebhookPayload' schemas: WebhookPayload: type: object description: >- The top-level webhook request payload containing a list of event objects. Events within a request are ordered by created_at in ascending order. required: - payload properties: payload: type: array description: >- A list of event objects, each representing a state change. items: $ref: '#/components/schemas/WebhookEvent' WebhookEvent: type: object description: >- An individual event record representing a state change within the Upvest Investment API. required: - id - created_at - event_type - object - webhook_id properties: id: type: string format: uuid description: >- The unique identifier of the event. Use this for idempotent processing. created_at: type: string format: date-time description: >- The timestamp when the event occurred. event_type: type: string description: >- The event type in CATEGORY.ACTION format. The category corresponds to the resource type, and the action describes what changed. examples: - USER.CREATED - USER.UPDATED - USER_CHECK.PASSED - USER_CHECK.FAILED - ACCOUNT.OPENED - ACCOUNT.CLOSED - ORDER.NEW - ORDER.PROCESSING - ORDER.FILLED - ORDER.CANCELLED - ORDER.REJECTED - ORDER_CANCELLATION.CONFIRMED - ORDER_CANCELLATION.REJECTED - EXECUTION.NEW - EXECUTION.SETTLED - EXECUTION.CANCELLED - POSITION.UPDATED - CASH_BALANCE.UPDATED - PORTFOLIO.CREATED - PORTFOLIO.UPDATED - REBALANCING.COMPLETED - REBALANCING.FAILED - SAVINGS_PLAN.EXECUTED - DIRECT_DEBIT.COMPLETED - DIRECT_DEBIT.FAILED - WITHDRAWAL.COMPLETED - WITHDRAWAL.FAILED - SECURITIES_TRANSFER.COMPLETED - CORPORATE_ACTION.PROCESSED - LIQUIDATION.COMPLETED - REPORT.READY - FEE.CHARGED object: $ref: '#/components/schemas/EventObject' webhook_id: type: string format: uuid description: >- The identifier of the webhook subscription that triggered this delivery. EventObject: type: object description: >- A reference to the resource that changed. required: - id - type properties: id: type: string format: uuid description: >- The unique identifier of the affected resource. type: type: string description: >- The resource type. enum: - USER - USER_CHECK - ACCOUNT - ACCOUNT_GROUP - ORDER - ORDER_CANCELLATION - EXECUTION - POSITION - CASH_BALANCE - PORTFOLIO - REBALANCING - SAVINGS_PLAN - DIRECT_DEBIT - WITHDRAWAL - MANDATE - SECURITIES_TRANSFER - ACCOUNT_TRANSFER - CORPORATE_ACTION - LIQUIDATION - REPORT - FEE