KeyCorp

KeyBank Webhooks

The KeyBank Webhooks service delivers real-time payment event notifications to subscribed commercial client applications for ACH, Wire, and RTP alerts. It defines client-hosted callback endpoints (alert codes such as AL00901, AL00906, and AL00907) that KeyBank invokes to push status and settlement events, allowing consuming systems to react to payment lifecycle changes without polling the inquiry APIs. Callback delivery follows the same OAuth2 and certificate-based security posture as the rest of the KeyBank API catalog.

GitHub OpenAPI

Documentation

📖
Documentation
https://developer.key.com/docs/webhooks

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/keycorp/refs/heads/main/openapi/keycorp-webhooks-openapi.yml

OpenAPI Specification

keycorp-webhooks-openapi.yml Raw ↑ 
openapi: 3.0.2
info:
  title: Webhooks
  description: Payment webhook service for ACH, Wire, and RTP alert notifications.
  contact:
    name : KeyBank Developer Support
    email: developers@keybank.com
  version: 3.1.0
paths:
  /"Callback URL from client for ACH alerts - AL00906":
    post:
      tags:
      - ACH
      summary: Send an ACH alerts event notification to the client URI.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/alertNotificationAL00906Request'
        required: true
      responses:
        200:
          description: OK
        202: 
          description: Accepted
        400:
          description: Invalid Input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/alertInvalidInputResponse'
        401:
          description: Authentication Error
        403:
          description: Authorization Error
        500:
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/alertFailureResponse'
  /"Callback URL from client for Wire/RTP alerts - AL00907":
    post:
      tags:
      - Wire/RTP v2
      summary: Send Wire/RTP Alerts event notification to the client URI.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/alertNotificationAL00907Request'
        required: true
      responses:
        200:
          description: OK
        202: 
          description: Accepted
        400:
          description: Invalid Input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/alertInvalidInputResponse'
        401:
          description: Authentication Error
        403:
          description: Authorization Error
        500:
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/alertFailureResponse'

  # Legacy alert - Please use AL00907 
  /"Callback URL from client for AL00901":
    post:
      tags:
      - Wire/RTP v1
      summary: Send Wire/RTP alerts event notification to the client URI.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/alertNotificationAL00901Request'
        required: true
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/alertSuccessResponse'
        400:
          description: Invalid Input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/alertInvalidInputResponse'
        401:
          description: Authentication Error
        403:
          description: Authorization Error
        500:
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/alertFailureResponse'
  
components:
  schemas:
    alertNotificationAL00907Request:
      type: object
      properties:
        alertNotificationRequest:
          type: array
          items:
            type: object
            properties:
              alertNotification:
                type: object
                properties:
                  alertHeader:
                    type: object
                    properties:
                      alertSentDateAndTime:
                        type: string
                        format: date-time
                        description: "Date and time the alert was sent. Format: (YYYY-MM-DD)T(HH:MM:SS)Z"
                      alertCode:
                        type: string
                        description: For Wire and RTP alerts, the alert code is AL00907.
                        enum:
                        - AL00907
                      payType:
                        type: string
                        description: "Identifies if the payment type is a Wire or RTP transaction. This value must be in all capital letters. Valid values: WIRE, RTP"
                        enum:
                        - RTP
                        - WIRE
                      eapAlertGUID:
                        type: string
                        format: uuid
                        description: Unique alert notification identifier generated by KeyBank (UUID v4).
                  alertBody:
                    type: object
                    properties:
                      transactionId:
                        type: string
                        description: The unique ID number associated with the original payment request.
                      transactionStatus:
                        type: string
                        description: "Status of the transaction. Possible values: IN_PROCESS, IN_REVIEW, FAILED, CANCELLED, COMPLETE"
                      transactionStatusTimeStamp:
                        type: string
                        format: date-time
                        description: Timestamp for the most recent status change on the transaction.
                      transactionDate:
                        type: string
                        description: "Date the transaction occurred. Format: YYYYMMDD"
                      transactionAmount:
                        type: string
                        description: The dollar amount of the transaction.
                      requestReference:
                        type: string
                        description: A reference value for the original request that is useful for traceability and reporting. 
                      sendersReference:
                        type: string
                        description: Sender tracking reference number returned from the request. 
                      channel:
                        type: string
                        description: "Indicates if the transaction is from the API or a batch channel. Valid values: API, BATCH"
                      transactionDirection:
                        type: string
                        description: "Indicates if the transaction is incoming or outgoing. Valid values: INBOUND, OUTBOUND, BOOK"
                      creditor:
                        type: object
                        description: Details about the creditor party. 
                        properties:
                          name:
                            type: string
                            description: Contains the customer identification number and the company name.
                  creditorAccount:
                    type: object
                    properties:
                      accountNumber:
                        type: string
                        description: Account number of the party.
                      virtualAccountNumber:
                        type: string
                        description: Account number for the virtual account (VAM).
                      currencyCode:
                        type: string
                        description: Indicates type of currency for the transaction amount.
                  debtor:
                    type: object
                    description: Details about the creditor party. 
                    properties:
                      name:
                        type: string
                        description: Contains the customer identification number and the company name.
                  debtorAccount:
                    type: object
                    properties:
                      accountNumber:
                        type: string
                        description: Account number of the party.
                      virtualAccountNumber:
                        type: string
                        description: Account number for the virtual account (VAM).
                      currencyCode:
                        type: string
                        description: Indicates type of currency for the transaction amount.
      example:
        alertNotificationRequest:
        - alertNotification:
              alertHeader:
                alertSentDateAndTime: "2025-04-14T10:50:56Z"
                alertCode: "AL00907"
                payType: "WIRE"
                eapAlertGUID: "f4d88cd2-446c-3cc4-9330-aa123456789"
              alertBody:
                transactionId: "US25032500068519"
                transactionStatus: "IN_PROCESS"
                transactionStatusTimeStamp: "2025-04-14T11:18:01Z"
                transactionDate: "20250325"
                transactionAmount: "6.48"
                requestReference: "36691398-42"
                sendersReference: "01234"
                channel: "API or BATCH"
                transactionDirection: "OUTBOUND"
                creditor:
                  name: "RTP GL Clearing Account"
                creditorAccount:
                  accountNumber: "1120108811111"
                  virtualAccountNumber: "953006666798343"
                  currencyCode: "USD"
                debtor:
                  name: "LINCOLN ELECTRIC CO"
                debtorAccount:
                  accountNumber: "149222222"
                  virtualAccountNumber: "953006666796016"
                  currencyCode: "USD"
    alertNotificationAL00906Request:
      type: object
      properties:
        alertNotificationRequest:
          type: array
          items:
            type: object
            properties:
              alertNotification:
                type: object
                properties:
                  alertHeader:
                    type: object
                    properties:
                      alertSentDateAndTime:
                        type: string
                        format: date-time
                        description: "Date and time the alert was sent. Format: (YYYY-MM-DD)T(HH:MM:SS)Z"
                      alertCode:
                        type: string
                        enum:
                        - AL00906
                        description: "For ACH alerts, the alert code is AL00906."
                      eapAlertGUID:
                        type: string
                        format: uuid
                        description: Unique alert notification identifier generated by KeyBank (UUID v4).
                  alertBody:
                    type: object
                    properties:
                      transactionStatus:
                        type: string
                        description: "The status of the ACH transaction. Valid values: COLLECTED, RETURNED, SETTLED"
                      transactionStatusTimeStamp:
                        type: string
                        format: date-time
                        description: Timestamp for the most recent status change on the transaction.
                      traceNumber:
                        type: string
                        description: The unique number for the transaction provided by the originator.
                      parNumber:
                        type: string
                        description: The unique PAR number assigned to the the transaction by the ACH product processor.
                      transactionAmount:
                        type: string
                        description: The dollar amount of the transaction.
                      collectionDate:
                        type: string
                        description: "Date the transaction was processed. Format: YYYY-MM-DD"
                      settlementDate:
                        type: string
                        description: "The date the transaction settlement occurred. Format: YYYY-MM-DD"
                      transactionCode:
                        type: string
                        description: Two-digit code identifying the account type at the receiving financial institution.
                      transactionDescription:
                        type: string
                        description: Description about the purpose of the transaction.
                      authorizedCustomerName:
                        type: string
                        description: Authorized customer name
                      standardEntryClassCode:
                        type: string
                        description: "Three-digit Standard Entry Class (SEC) code based on Nacha rules. Valid values: CCD, CTX, PPD, TEL, WEB"
                      receivingAccountNumber:
                        type: string
                        description: Account number of the person or institution receiving the funds. 
                      receivingCustomerIdentificationNumber:
                        type: string
                        description: The customer identification number for the person receiving the transaction.
                      receivingCompanyName:
                        type: string
                        description: Company name of the institution getting the funds. 
                      originatingAccountNumber:
                        type: string
                        description: Account number of the ACH transaction originator.
                      originatingCustomerIdentificationNumber:
                        type: string
                        description: Originating customer identification number
                      originatingCompanyName:
                        type: string
                        description: Company name of the or associated with the ACH originator. 
                      returnReasonCode:
                        type: string
                        description: "The code associated with the reason for returning the ACH transaction. The code is the letter 'R' for reason followed by a two-digit numeric code. Format: R00"
                      returnReasonDescription:
                        type: string
                        description: Description as to why the ACH transaction is returned. 
                      returnDate:
                        type: string
                        description: "Date of the returned transaction to the ACH system. Format:YYYY-MM-DD"
                      notificationOfChangeAddendaCount:
                        type: string
                        description: Count of change notifications for addenda records. 
                      internationalAddendaCount:
                        type: string
                        description: Count of the international addenda records.
                      addendaCount:
                        type: string
                        description: Count of addenda records.
      example:
        alertNotificationRequest:
        - alertNotification:
            alertHeader:
              alertSentDateAndTime: "2024-07-15T16:46:01Z"
              alertCode: "AL00906"
              eapAlertGUID: "4g0fda4b-156f-483c-98ae-bd8ccab266h0"
            alertBody:
              transactionStatus: "COLLECTED"
              transactionStatusTimestamp: 2024-07-15T18:18:01
              traceNumber: "41033956478656"
              parNumber: "22010008879477"
              transactionAmount: "287.40"
              collectionDate: "12-JAN-22"
              settlementDate: "12-JAN-22"
              transactionCode: "22"
              transactionDescription: "PAYMENT"
              authorizedCustomerName: "HIGHMARK INC."
              standardEntryClassCode: "CCD"
              receivingAccountNumber: "00000000001000004133"
              receivingCustomerIdentificationNumber: "65A658990"
              receivingCompanyName: "LEHIGH GASTROENTEROLOG"
              originatingAccountNumber: "00000000001000005244"
              originatingCustomerIdentificationNumber: "7498659450"
              originatingCompanyName: "HIGHMARK INC."
              returnReasonCode: "R29"
              returnReasonDescription: "Corporate Customer Advises Not Authorized"
              returnDate: "07-DEC-21"
              notificationOfChangeAddendaCount: "1"
              internationalAddendaCount: "0"
              addendaCount: "0"

    # Legacy schema - Please use AL00907
    alertNotificationAL00901Request:
      type: object
      properties:
        alertNotificationRequest:
          type: array
          items:
            type: object
            properties:
              alertNotification:
                type: object
                properties:
                  alertHeader:
                    type: object
                    properties:
                      alertSentDateAndTime:
                        type: string
                        format: date-time
                        description: "Date and time the alert was sent. Format: (YYYY-MM-DD)T(HH:MM:SS)Z"
                      alertCode:
                        type: string
                        enum:
                        - AL00901
                        description: "For Wire and RTP alerts, the alert code is AL00901."
                      eapAlertGUID:
                        type: string
                        format: uuid
                        description: Unique alert notification identifier. 
                  alertBody:
                    type: object
                    properties:
                      crOrDbCode:
                        type: string
                        description: "Identifies the transaction type as credit or debit. Valid values: C (credit), D (debit)"
                      crArngNum:
                        type: string
                        description: Account number of the credit account.
                      crArngTypeCode:
                        type: string
                        description: Type code of the credit account.
                      crArngBankNum:
                        type: string
                        description: Bank number of the credit account.
                      crTranCurrencyCode:
                        type: string
                        description: Transaction currency code of the credit account.
                      dbArngTypeCode:
                        type: string
                        description: Type code of the debit account
                      dbTranCurrencyCode:
                        type: string
                        description: Transaction currency code of the debit account.
                      requestReferenceNumber:
                        type: string
                        maxLength: 32
                        description: "Unique identification number for an originating wire or RTP transaction. This number is limited to 32 characters."
                      crIpId:
                        type: string
                        description: Customer number associated with the credit account.
                      crIpNm:
                        type: string
                        description: Customer name associated with the credit account.
                      dbArngNum:
                        type: string
                        description: Account number of the debit account.
                      dbArngBankNum:
                        type: string
                        description: Bank number of the debit account.
                      dbIpId:
                        type: string
                        description: Customer number associated with the debit account.
                      dbIpNm:
                        type: string
                        description: Customer name associated with the debit account.
                      payNotifyTs:
                        type: string
                        description: Timestamp of the payment event.
                      wireEventNm:
                        type: string
                        description: Payment status code
                      tranAmt:
                        type: string
                        description: Dollar amount of the transaction.
                      tranExecutedDt:
                        type: string
                        description: "Date the transaction is executed. Format: YYYYMMDD"
                      federalReferNum:
                        type: string
                        description: Federal reference number
                      sndngBankReferNum:
                        type: string
                        description: Reference number attached to a wire, issued by the sending bank.
                      tranId:
                        type: string
                        description: Unique transaction identifier
                      tranBusnStatusCode:
                        type: string
                        description: Transaction business status code
                      wireDirectionCode:
                        type: string
                        description: Indicates the direction of the transaction.
                      tranType:
                        type: string
                        description: Type of transaction.
                      tranValueTypeCode:
                        type: string
                        description: Identifies the value of a transaction.
                      wireProcessTypeCode:
                        type: string
                        description: Wire processing type code
                      benefitAba:
                        type: string
                        description: ABA routing number of the beneficiary.
                      benefitArngNum:
                        type: string
                        description: Account number of the beneficiary.
                      benefitIpAddrLine:
                        type: string
                        description: Address lines 1-7 (array) of the beneficiary.
                      benefitBicCode:
                        type: string
                        description: BIC number of the beneficiary.
                      benefitBankAbaNum:
                        type: string
                        description: ABA routing number of the beneficiary's bank.
                      benefitBankArngNum:
                        type: string
                        description: Account number of the beneficiary's bank.
                      benefitBankAddrLine:
                        type: string
                        description: Address lines 1-7 (array) of the beneficiary's bank.
                      benefitBankBicCode:
                        type: string
                        description: BIC number of the beneficiary's bank.
                      benefitBankNm:
                        type: string
                        description: Name of the beneficiary's bank.
                      intrmdryBankAbaNum1:
                        type: string
                        description: ABA routing number of the intermediary bank 1.
                      intrmdryBankAddrLine1:
                        type: string
                        description: Address lines 1-7 (array) of the intermediary bank 1.
                      intrmdryBankNm1:
                        type: string
                        description: Name of the intermediary bank 1.
                      intrmdryBicCode1:
                        type: string
                        description: BIC number of the intermediary bank 1.
                      intrmdryBankAbaNum2:
                        type: string
                        description: ABA routing number of the intermediary bank 2.
                      intrmdryBankAddrLine2:
                        type: string
                        description: Address lines 1-7 (array) of the intermediary bank 2.
                      intrmdryBankNm2:
                        type: string
                        description: Name of the intermediary bank 2.
                      intrmdryBicCode2:
                        type: string
                        description: BIC number of the intermediary bank 2.
                      intrmdryBankAbaNum3:
                        type: string
                        description: ABA routing number of the intermediary bank 3.
                      intrmdryBankAddrLine3:
                        type: string
                        description: Address lines 1-7 (array) of the intermediary bank 3.
                      intrmdryBankNm3:
                        type: string
                        description: Name of the intermediary bank 3.
                      intrmdryBicCode3:
                        type: string
                        description: BIC number of the intermediary bank 3.
                      orgntngBankAbaNum:
                        type: string
                        description: ABA routing number of the wire originator's bank.
                      orgntngBankAddrLine:
                        type: string
                        description: Address lines 1-7 (array) of the wire originator's bank.
                      orgntngBankBicCode:
                        type: string
                        description: BIC number of the wire originator's bank.
                      orgntngBankNm:
                        type: string
                        description: Name of the wire originator's bank.
                      orgntngAba1:
                        type: string
                        description: ABA routing number of the originator 1.
                      orgntngArngNum1:
                        type: string
                        description: Account number of the originator 1.
                      orgntngIpNm1:
                        type: string
                        description: Name of the originator 1.
                      orgntngIpAddrLine1:
                        type: string
                        description: Address lines 1-7 (array) of the originator 1.
                      orgntngAba2:
                        type: string
                        description: ABA routing number of the originator 2.
                      orgntngArngNum2:
                        type: string
                        description: Account number of the originator 2.
                      orgntngIpNm2:
                        type: string
                        description: Name of the originator 2.
                      orgntngIpAddrLine2:
                        type: string
                        description: Address lines 1-7 (array) of the originator 2.
                      orgntngAba3:
                        type: string
                        description: ABA routing number of the originator 3.
                      orgntngArngNum3:
                        type: string
                        description: Account number of the originator 3.
                      orgntngIpNm3:
                        type: string
                        description: Name of the originator 3.
                      orgntngIpAddrLine3:
                        type: string
                        description: Address lines 1-7 (array) of the originator 3.
                      crVirtualNum:
                        type: string
                        description: Virtual account number of the credit account.
                      dbVirtualNum:
                        type: string
                        description: Virtual account number of the debit account.
      example:
        alertNotificationRequest:
          - alertNotification:
              alertHeader:
                alertSentDateAndTime: '2023-02-1159T10:20:56Z'
                alertCode: AL00901
                payType: WIRE
                eapAlertGUID: f4d88cd2-446c-3cc4-9330-aa123456789
              alertBody:
                crOrDbCode: C
                crArngNum: '359123456789'
                crArngTypeCode: DDA
                crArngBankNum: '0101'
                crTranCurrencyCode: USD
                dbArngTypeCode: DDA
                dbTranCurrencyCode: USD
                requestReferenceNumber: '4630123-20240212161123'
                crIpId: '999997'
                crIpNm: BANKOFTEST
                dbArngNum: '201907987654321'
                dbArngBankNum: '0101'
                dbIpId: '30472222'
                dbIpNm: Test Name
                payNotifyTs: '1673615327943'
                wireEventNm: WirePaymentTransactionEvent
                tranAmt: '12.79'
                tranExecutedDt: '20230112'
                federalReferNum: 'null'
                sndngBankReferNum: 'null'
                tranId: US23010987654321
                tranBusnStatusCode: RegulatoryFilter
                wireDirectionCode: OUTBOUND
                tranType: 'null'
                tranValueTypeCode: 'N'
                wireProcessTypeCode: 'null'
                benefitAba: 'null'
                benefitArngNum: '3435656765'
                benefitIpAddrLine: 250 Delaware Ave St
                benefitBicCode: KEYBUS33 XXX
                benefitBankAbaNum: 'null'
                benefitBankArngNum: 'null'
                benefitBankAddrLine: 250 Delaware Ave St
                benefitBankBicCode: KEYBUS33 XXX
                benefitBankNm: KeyBank National Association
                intrmdryBankAbaNum1: 'null'
                intrmdryBankAddrLine1: 'null'
                intrmdryBankNm1: KeyBank National Association
                intrmdryBicCode1: '21300077'
                intrmdryBankAbaNum2: 'null'
                intrmdryBankAddrLine2: 'null'
                intrmdryBankNm2: BANKOFTEST
                intrmdryBicCode2: KEYBUS33 XXX
                intrmdryBankAbaNum3: 'null'
                intrmdryBankAddrLine3: 'null'
                intrmdryBankNm3: 'null'
                intrmdryBicCode3: 'null'
                orgntngBankAbaNum: 'null'
                orgntngBankAddrLine: 'null'
                orgntngBankBicCode: 'null'
                orgntngBankNm: 'null'
                orgntngAba1: 'null'
                orgntngArngNum1: '123456789'
                orgntngIpNm1: 'TEST COMPANY 1, LLC'
                orgntngIpAddrLine1: '127 Public Sq, Cleveland,OH 44114,US'
                orgntngAba2: 'null'
                orgntngArngNum2: 'null'
                orgntngIpNm2: 'null'
                orgntngIpAddrLine2: 'null'
                orgntngAba3: 'null'
                orgntngArngNum3: 'null'
                orgntngIpNm3: 'null'
                orgntngIpAddrLine3: 'null'
                crVirtualNum: '953456789'
                dbVirtualNum: '953654321'
    alertSuccessResponse:
      type: object
      properties:
        alertNotificationResponse:
          type: array
          items:
            type: object
            properties:
              alertAcknowledgment:
                type: object
                properties:
                  alertStatus:
                    type: string
                    description: Indicates if the alert was a success or failure. 
                    enum:
                    - SUCCESS
                  confirmationGUID:
                    type: string
                    description: API Customer Unique ID for the Alert Notification
                    format: uuid
                  alertRecievedDateAndTime:
                    type: string
                    format: date-time
                    description: "Date and time the alert was received. Format: (YYYY-MM-DD)T(HH:MM:SS)Z"
                  eapAlertGUID:
                    type: string
                    description: Unique alert notification identifier passed through from the request.
                    format: uuid
                  message:
                    type: string
                    description: Free-form text field to describe the response.
      example:
        alertNotificationResponse:
        - alertAcknowledgment:
            alertStatus: SUCCESS
            confirmationGUID: 5f0ada5b-056f-483c-98ae-ac6ccab269c1
            alertRecievedDateAndTime: 2021-11-19T10:31:12Z
            eapAlertGUID: 5163dee6-0b2b-4901-9f6a-4b3997ee8d77
            message: Successfully submitted the request
    alertInvalidInputResponse:
      type: object
      properties:
        alertNotificationResponse:
          type: array
          items:
            type: object
            properties:
              alertAcknowledgment:
                type: object
                properties:
                  alertStatus:
                    type: string
                    enum:
                    - FAILURE
                  confirmationGUID:
                    type: string
               

# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/keycorp/refs/heads/main/openapi/keycorp-webhooks-openapi.yml