OpenRPCMethods

Notifications

Document one-way JSON-RPC calls that don’t expect a response

Notifications in JSON-RPC are one-way method calls that don’t expect a response from the server. They’re useful for fire-and-forget operations like logging, analytics, or triggering background processes.

Basic notifications

Define a notification by omitting the result property:

openrpc.yml
1methods:
2  - name: analytics.track
3    summary: Track user analytics event
4    description: Send an analytics event (no response expected)
5    params:
6      - name: event
7        schema:
8          type: object
9          properties:
10            userId:
11              type: string
12            eventType:
13              type: string
14              enum: [page_view, click, conversion, signup]
15            properties:
16              type: object
17              additionalProperties: true
18            timestamp:
19              type: string
20              format: date-time
21          required:
22            - userId
23            - eventType
24        required: true
25    # Note: No result property - this makes it a notification
26    examples:
27      - name: PageViewEvent
28        description: Track a page view
29        params:
30          event:
31            userId: "user_123"
32            eventType: "page_view"
33            properties:
34              page: "/dashboard"
35              referrer: "https://google.com"
36            timestamp: "2024-01-15T10:30:00Z"

Logging notifications

Use notifications for logging and monitoring:

openrpc.yml
1methods:
2  - name: log.error
3    summary: Log an error event
4    description: Send error information for monitoring (fire and forget)
5    params:
6      - name: errorData
7        schema:
8          type: object
9          properties:
10            level:
11              type: string
12              enum: [error, warning, info, debug]
13            message:
14              type: string
15            stackTrace:
16              type: string
17            userId:
18              type: string
19            sessionId:
20              type: string
21            metadata:
22              type: object
23              additionalProperties: true
24          required:
25            - level
26            - message
27        required: true
28    examples:
29      - name: ApplicationError
30        description: Log an application error
31        params:
32          errorData:
33            level: "error"
34            message: "Database connection failed"
35            stackTrace: "Error: Connection timeout\n  at Database.connect (db.js:45)"
36            userId: "user_456"
37            sessionId: "session_789"
38            metadata:
39              component: "user-service"
40              version: "1.2.3"

Real-time updates

Send real-time updates without expecting responses:

openrpc.yml
1methods:
2  - name: presence.update
3    summary: Update user presence status
4    description: Notify about user presence changes
5    params:
6      - name: presenceData
7        schema:
8          type: object
9          properties:
10            userId:
11              type: string
12            status:
13              type: string
14              enum: [online, away, busy, offline]
15            lastSeen:
16              type: string
17              format: date-time
18            customMessage:
19              type: string
20              maxLength: 100
21          required:
22            - userId
23            - status
24        required: true
25    examples:
26      - name: UserOnline
27        description: User comes online
28        params:
29          presenceData:
30            userId: "user_123"
31            status: "online"
32            lastSeen: "2024-01-15T10:30:00Z"
33            customMessage: "Working on the new feature"

Background processing

Trigger background tasks without waiting for completion:

openrpc.yml
1methods:
2  - name: email.send
3    summary: Send email notification
4    description: Queue an email for sending (background processing)
5    params:
6      - name: emailRequest
7        schema:
8          type: object
9          properties:
10            to:
11              type: array
12              items:
13                type: string
14                format: email
15              minItems: 1
16            subject:
17              type: string
18            body:
19              type: string
20            templateId:
21              type: string
22            variables:
23              type: object
24              additionalProperties: true
25            priority:
26              type: string
27              enum: [low, normal, high, urgent]
28              default: normal
29          required:
30            - to
31            - subject
32            - body
33        required: true
34    examples:
35      - name: WelcomeEmail
36        description: Send welcome email to new user
37        params:
38          emailRequest:
39            to: ["newuser@example.com"]
40            subject: "Welcome to our platform!"
41            body: "Thank you for signing up..."
42            templateId: "welcome_template"
43            variables:
44              userName: "John Doe"
45              activationLink: "https://app.example.com/activate/123"
46            priority: "normal"

Cache invalidation

Notify about cache invalidation events:

openrpc.yml
1methods:
2  - name: cache.invalidate
3    summary: Invalidate cache entries
4    description: Notify cache system to invalidate specific entries
5    params:
6      - name: invalidationRequest
7        schema:
8          type: object
9          properties:
10            keys:
11              type: array
12              items:
13                type: string
14              description: Cache keys to invalidate
15            pattern:
16              type: string
17              description: Pattern for batch invalidation
18            namespace:
19              type: string
20              description: Cache namespace
21          anyOf:
22            - required: [keys]
23            - required: [pattern]
24        required: true
25    examples:
26      - name: InvalidateUserCache
27        description: Invalidate user-related cache entries
28        params:
29          invalidationRequest:
30            keys: ["user:123", "user:123:profile", "user:123:settings"]
31            namespace: "users"
32      - name: InvalidatePatternCache
33        description: Invalidate all product cache entries
34        params:
35          invalidationRequest:
36            pattern: "product:*"
37            namespace: "catalog"

Audit logging

Record audit events for compliance:

openrpc.yml
1methods:
2  - name: audit.record
3    summary: Record audit event
4    description: Log security and compliance events
5    params:
6      - name: auditEvent
7        schema:
8          type: object
9          properties:
10            eventType:
11              type: string
12              enum: [login, logout, data_access, data_modification, permission_change]
13            actor:
14              type: object
15              properties:
16                userId:
17                  type: string
18                email:
19                  type: string
20                ipAddress:
21                  type: string
22                userAgent:
23                  type: string
24              required: [userId]
25            resource:
26              type: object
27              properties:
28                type:
29                  type: string
30                id:
31                  type: string
32                name:
33                  type: string
34            timestamp:
35              type: string
36              format: date-time
37            metadata:
38              type: object
39              additionalProperties: true
40          required:
41            - eventType
42            - actor
43            - timestamp
44        required: true
45    examples:
46      - name: LoginAudit
47        description: Record user login event
48        params:
49          auditEvent:
50            eventType: "login"
51            actor:
52              userId: "user_123"
53              email: "john@example.com"
54              ipAddress: "192.168.1.100"
55              userAgent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
56            timestamp: "2024-01-15T10:30:00Z"
57            metadata:
58              loginMethod: "password"
59              mfaUsed: true

Notification best practices

  • Use notifications for fire-and-forget operations where you don’t need to know if the operation succeeded
  • Consider using regular methods with results for critical operations that need confirmation
  • Include enough context in notification parameters for proper processing
  • Use structured schemas even for notifications to maintain API consistency
  • Consider implementing client-side queuing for notifications in unreliable network conditions

Notifications are perfect for decoupling systems and improving performance by not waiting for non-critical operations to complete.