Events API
Jack Henry Modern Eventing
>
API Reference
>
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'
Have a Question?
- Have a how-to question? Seeing a weird error? Get help on StackOverflow.
- Register for the Developer Office Hours where we answer technical Q&A from the audience.
Did this page help you?
Why was this page helpful?
Why wasn't this page helpful?
Thank you for your feedback!
Last updated Wed Aug 7 2024