Events API

openapi: 3.0.3 info: title: JH-Events Persistence API version: 1.0.0 description: Query API for stored events and dispatch attempts. contact: name: Team Icarus url: https://www.jackhenry.com/ email: jh-gcp-gbl-icarus-engineering@jackhenry.com servers: - url: https://banno.com description: Production environment - url: https://platform.banno-staging.com description: Staging environment - url: https://platform.banno-development.com description: Development environment tags: - name: Events description: Event query and search operations paths: /a/api/enterprise-event/v1/{institutionId}/events/{subscriptionId}: get: x-ignoreRules: - comm-404-Response - comm-GET-Response-Code-404. summary: Get Events for Subscription (Legacy) description: | Returns events for a specific subscription. This is the legacy endpoint that provides backwards compatibility. Always returns up to 1000 events (hard-coded limit). For advanced filtering and pagination, use the search endpoint. operationId: getSubscriptionEvents tags: - Events security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/InstitutionIdPathParam' - $ref: '#/components/parameters/SubscriptionIdPathParam' responses: '200': $ref: '#/components/responses/SubscriptionEventArrayResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/UnexpectedError' /a/api/enterprise-event/v1/{institutionId}/events/{subscriptionId}/search: post: summary: Search Events with Advanced Filtering description: | Advanced search for subscription events with filtering and pagination capabilities. Supports filtering by event IDs, event numbers, time ranges, and dispatch status. operationId: searchSubscriptionEvents tags: - Events security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/InstitutionIdPathParam' - $ref: '#/components/parameters/SubscriptionIdPathParam' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/EventSearchRequest' example: dispatchStatus: - failed - pending pendingLongerThan: 30m eventNumFilter: - '1000' - '1001' - '2000' fromTime: '2024-01-01T00:00:00Z' toTime: '2024-01-31T23:59:59Z' sortBy: subscriptionTime includePayload: false limit: 50 responses: '200': $ref: '#/components/responses/EventSearchResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/UnexpectedError' /a/api/enterprise-event/v1/{institutionId}/events/{eventId}/attempts: get: summary: Get Dispatch Attempts for Event description: | Returns all dispatch attempts for a specific event, including success/failure status, timestamps, and target information. operationId: getEventAttempts tags: - Events security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/InstitutionIdPathParam' - $ref: '#/components/parameters/EventIdPathParam' responses: '200': $ref: '#/components/responses/DispatchAttemptArrayResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/UnexpectedError' components: securitySchemes: bearerAuth: description: OpenIDConnect JWT Token type: http scheme: bearer bearerFormat: JWT parameters: InstitutionIdPathParam: name: institutionId in: path description: Institution unique identifier required: true schema: type: string format: uuid example: 12345678-1234-1234-1234-123456789012 SubscriptionIdPathParam: name: subscriptionId in: path description: Subscription unique identifier required: true schema: type: string format: uuid example: 87654321-4321-4321-4321-210987654321 EventIdPathParam: name: eventId in: path description: Event unique identifier required: true schema: type: string format: uuid example: 11111111-2222-3333-4444-555555555555 schemas: SubscriptionEvent: type: object description: A subscription event stored in the persistence layer properties: subscriptionId: type: string description: Subscription identifier example: 87654321-4321-4321-4321-210987654321 institutionId: type: string description: Institution identifier example: 12345678-1234-1234-1234-123456789012 subscriptionName: type: string description: Subscription name example: My Subscription dispatchBatchId: type: string format: uuid description: Dispatch batch ID (if batched) nullable: true example: e48f638e-e6ad-4d93-a16a-9ffb6cfcd30f eventId: type: string description: Event identifier example: event-123 eventNum: type: string description: Event number example: '1001' dispatchStatus: type: string description: Computed dispatch status based on latest attempt enum: - succeeded - failed - pending example: succeeded attemptId: type: string description: Attempt identifier (null for pending events) nullable: true example: attempt-123 successful: type: boolean description: Whether the dispatch was successful (null for pending events) nullable: true example: true source: type: string description: Event source (null for pending events) nullable: true example: 2020Teller target: type: string description: Dispatch target URL nullable: true example: https://example.com/webhook sentAt: type: string format: date-time description: When the dispatch was sent (null for pending events) nullable: true example: '2024-01-15T10:30:03Z' timeInQueue: type: number format: double description: Time spent in queue in seconds (null for pending events) nullable: true example: 1.5 rawEventData: type: string description: Original event data (only included when includePayload=true) nullable: true example: <event>...</event> rawEventDataType: type: string description: Type of raw event data (only included when includePayload=true) nullable: true example: xml processedXml: type: string description: Processed XML representation (only included when includePayload=true) nullable: true example: <processedEvent>...</processedEvent> processedJson: type: string description: Processed JSON representation (only included when includePayload=true) nullable: true example: '{"event": {...}}' StandardErrorType: description: A string path which uniquely classifies the domain of the error. type: string nullable: false example: jackhenry/operation-failed StandardErrorTitle: description: A end-user readable string title of the error type. nullable: false type: string StandardErrorDetails: description: An array of end-user readable strings which provide additional details for the error message. type: array nullable: false items: type: string StandardErrorData: type: object description: | Additional data that could be useful to a developer or for handing the error programmatically. The schema for the data in this object is intentionally left undefined. nullable: true StandardError: type: object required: - type - title - details properties: type: $ref: '#/components/schemas/StandardErrorType' title: $ref: '#/components/schemas/StandardErrorTitle' details: $ref: '#/components/schemas/StandardErrorDetails' data: $ref: '#/components/schemas/StandardErrorData' EventSearchRequest: type: object description: Advanced search request for subscription events properties: dispatchStatus: type: array description: | Filter by dispatch status. Accepts multiple values (OR'd together). Empty or omitted returns all events. items: type: string enum: - succeeded - failed - pending nullable: true example: - failed - pending pendingLongerThan: type: string description: | Duration threshold for pending events (e.g., "30s", "15m", "2h", "1d"). Only valid when dispatchStatus includes "pending". Filters to pending events older than this threshold. nullable: true example: 30m sortBy: type: string description: | Sort order for results. Default is "subscriptionTime". "sentAt" requires dispatchStatus to be specified and cannot include "pending". enum: - subscriptionTime - sentAt default: subscriptionTime example: subscriptionTime includePayload: type: boolean description: | Include full event payload in response. Default is false. When true, includes rawEventData, rawEventDataType, processedXml, and processedJson fields. default: false example: false eventIdFilter: type: array description: Filter by specific event IDs items: type: string nullable: true example: - event-123 - event-456 eventNumFilter: type: array description: Filter by specific event numbers items: type: string nullable: true example: - '1001' - '1002' - '1003' dispatchBatchIdFilter: type: array description: Filter by dispatch batch IDs items: type: string format: uuid nullable: true example: - e48f638e-e6ad-4d93-a16a-9ffb6cfcd30f fromTime: type: string format: date-time description: Start of time range filter (filters on SubscriptionTime - when event was received) nullable: true example: '2024-01-01T00:00:00Z' toTime: type: string format: date-time description: End of time range filter (filters on SubscriptionTime - when event was received) nullable: true example: '2024-01-31T23:59:59Z' limit: type: integer minimum: 1 maximum: 1000 default: 100 description: Maximum number of events to return example: 50 nextId: type: string description: Token for pagination (from previous response) nullable: true example: next-id-token EventSearchResponse: type: object description: Response for advanced event search properties: events: type: array description: Array of matching events items: $ref: '#/components/schemas/SubscriptionEvent' nextId: type: string description: Token for next page (if more results available) nullable: true example: next-id-token-abc123 DispatchAttempt: type: object description: A dispatch attempt record for an event properties: attemptId: type: string description: Attempt identifier example: attempt-123 batchId: type: string format: uuid description: Batch ID if this attempt was part of a batch dispatch nullable: true example: e48f638e-e6ad-4d93-a16a-9ffb6cfcd30f successful: type: boolean description: Whether the attempt was successful example: true source: type: string description: Event source example: 2020Teller target: type: string description: Target URL for the dispatch nullable: true example: https://example.com/webhook sentAt: type: string format: date-time description: When the dispatch attempt was made example: '2024-01-15T10:30:03Z' responses: SubscriptionEventArrayResponse: description: Events retrieved successfully content: application/json: schema: type: array items: $ref: '#/components/schemas/SubscriptionEvent' BadRequest: description: The server could not understand the request due to an invalid request. content: application/problem+json: schema: $ref: '#/components/schemas/StandardError' Unauthorized: description: Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. Forbidden: description: The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401, the clients identity is known to the server. UnexpectedError: description: An unexpected internal server error occurred while processing the request. content: application/problem+json: schema: $ref: '#/components/schemas/StandardError' examples: internalServerError: summary: Internal server error value: type: general/internal-server-error title: Internal server error details: - Unexpected internal server error EventSearchResponse: description: Search completed successfully content: application/json: schema: $ref: '#/components/schemas/EventSearchResponse' DispatchAttemptArrayResponse: description: Dispatch attempts retrieved successfully content: application/json: schema: type: array items: $ref: '#/components/schemas/DispatchAttempt'

Please ignore this field