Event Subscription Guide

Interface Description

The Events Subscription service is implemented as a server-streaming persistent connection based on the gRPC framework. It is designed for Webull customers integrating through the OpenAPI development platform to receive real-time event notifications in a reliable and efficient manner.

This service fully complies with the official gRPC open-source protocol specification. Clients can leverage standard gRPC libraries and SDKs (https://grpc.io/docs/) to establish and maintain the streaming connection.

Through this subscription channel, the server continuously pushes structured event messages to clients once the connection is established, eliminating the need for repeated polling and ensuring low-latency data delivery.

Event Modules Overview

The message push service is organized into the following functional modules. Each module can be subscribed to independently based on business needs.

Module Name	Description
Application Events	Account application lifecycle events, including submission and status updates.
Account Events	Account-level updates such as status changes and configuration updates.
Funding Events	Deposit and withdrawal related events and status notifications.
Fees and Credits Events	Fee charges, and credit postings.
Journal Events	Internal transfers and journal entry notifications.
Master Data Events	Trading calendar change notifications.
Instrument Events	Instrument-level updates such as trading status or metadata changes.
Trade Events	Order execution, trade confirmations, and related transaction updates.
Corporate Actions Events	Corporate action announcements and processing updates.
Event Contract Events	Event contract lifecycle and status updates.
SOD Events	Start-of-Day processing results and daily initialization updates.

Clients may selectively subscribe to one or more modules depending on their integration scope and operational requirements.

Events subscribe Proto protocol definition.

Complete Description of Event gRPC/Protobuf Protocol

syntax = "proto3";

package grpc.event;
option go_package = ".;grpc_event";

service EventService {
	rpc Subscribe(SubscribeRequest) returns (stream SubscribeResponse) {}
}

message SubscribeRequest {
	 repeated SubscribeEvent events = 1;
	 string timestamp = 2;
}

message SubscribeResponse {
	 Type type = 1;
	 string id = 2;
	 string eventType = 3;
	 string position = 4;
	 string  timestamp = 5; 
	 string version = 6;
	 string payload = 7;
}

enum Type {
	SubscribeSuccess = 0;
	Ping = 1;
	Event = 2;
	AuthError = 3;
	NumOfConnExceed = 4;
	SubscribeExpired = 5;
}

message SubscribeEvent {
	string eventType = 1;
	string position = 2;
}

Request Proto

message SubscribeRequest {
	 repeated SubscribeEvent events = 1;
	 string timestamp = 2;
}
message SubscribeEvent {
	string eventType = 1;
	string position = 2;
}

Response Proto

message SubscribeResponse {
	 Type type = 1;
	 string id = 2;
	 string eventType = 3;
	 string position = 4;
	 string  timestamp = 5; 
	 string version = 6;
	 string payload = 7;
}

Type enumeration

enum Type {
	SubscribeSuccess = 0;
	Ping = 1;
	Event = 2;
	AuthError = 3;
	NumOfConnExceed = 4;
	SubscribeExpired = 5;
}

Request Example

For native Python integration, please use the sample code included in the ZIP package: python_event_subscription_sample.zip

Response Payload Example

Event scene type

ACCOUNT_CREATE(APPROVED)

{
    "id": "event_c4b2c210-ce32-41d4-a9a1-cfad4fdf191c",
    "event_type": "APPLICATION",
    "position": "CJO1fxACGAAgADAB",
    "timestamp": "2025-03-29T07:02:33.200962333Z",
    "payload": {
        "client_request_id": "ndjanww3004abe894b51244560kmdcd",
        "application_id": "d44caf9eb12d4abe894b529699059ec5",
        "biz_type": "ACCOUNT_CREATE",
        "status": "APPROVED",
        "reason": "",
        "timestamp": "2025-11-21T06:27:43.312Z"
    }
}