Set up and manage webhook subscriptions to receive real-time notifications about key events, like transactions, account changes, or client onboarding, directly to your platform, so you can automate workflows and respond instantly as events happen. This API lets you create, update, and monitor your webhook endpoints, giving you fine-grained control over which events you track and how you handle them.
# Harvested verbatim from the J.P. Morgan Payments Developer Portal.
# method: searched
# source: https://developer.payments.jpmorgan.com/api/llm-content?path=en%2Fapi%2Fembedded-finance-solutions%2Fembedded-payments%2Fembedded-payments%2Fwebhooks.md
# generated: '2026-07-28'
openapi: 3.0.1
info:
title: Webhooks API
version: 1.0.55
description: Set up and manage webhook subscriptions to receive real-time notifications about key events,
like transactions, account changes, or client onboarding, directly to your platform, so you can automate
workflows and respond instantly as events happen. This API lets you create, update, and monitor your
webhook endpoints, giving you fine-grained control over which events you track and how you handle
them.
contact:
name: JPMC Technical Services Support
servers:
- url: https://api.payments.jpmorgan.com/embedded/v1
description: PRODUCTION - MTLS
- url: https://api-mock.payments.jpmorgan.com/embedded/v1
description: MOCK
- url: https://api-sandbox.payments.jpmorgan.com/embedded/v1
description: CLIENT TESTING - MTLS
tags:
- name: Webhooks
description: Create and manage webhook subscriptions for your platform.
paths:
/webhooks:
get:
summary: List webhooks
description: List all your webhooks
operationId: listWebhooks
tags:
- Webhooks
parameters:
- $ref: '#/components/parameters/pageNo'
- $ref: '#/components/parameters/pageSize'
responses:
'200':
description: Ok.
content:
application/json:
schema:
$ref: '#/components/schemas/ListWebhookResponse'
examples:
ListWebhooks:
$ref: '#/components/examples/ListWebhooks'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'500':
$ref: '#/components/responses/500'
'503':
$ref: '#/components/responses/503'
post:
summary: Create a webhook subscription.
description: Create a webhook subscription
operationId: createWebhook
tags:
- Webhooks
parameters: []
requestBody:
required: true
description: Create a new webhook request.
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookRequest'
examples:
Create a new webhook and event subscription:
summary: Create a new webhook
description: Create a new webhook
value:
subscriptions:
- eventType: TRANSACTION_COMPLETED
responses:
'201':
description: Created.
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookResponse'
examples:
CreateAWebhookRes:
$ref: '#/components/examples/CreateAWebhookRes'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'500':
$ref: '#/components/responses/500'
'503':
$ref: '#/components/responses/503'
callbacks:
Transaction Event Callback:
Callback URL:
post:
summary: Transaction Event Callback
description: Triggered when a transaction is completed or failed.
operationId: transactionEventCallback
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionCallbackEvent'
responses:
'200':
description: Callback accepted.
Account Event Callback:
Callback URL:
post:
summary: Account Event Callback
description: Triggered when a client account is created, closed, overdrawn or a restriction
is applied.
operationId: accountEventCallback
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AccountCallbackEvent'
responses:
'200':
description: Callback accepted.
Recipient Event Callback:
Callback URL:
post:
summary: Recipient Event Callback
description: Triggered when a recipient validation event occurs.
operationId: recipientEventCallback
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RecipientsCallbackEvent'
responses:
'200':
description: Callback accepted.
Client Event Callback:
Callback URL:
post:
summary: Client Event Callback
description: Triggered when a client's onboarding status changes, or more information is
required.
operationId: clientEventCallback
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ClientCallbackEvent'
responses:
'200':
description: Callback accepted.
Party Event Callback:
Callback URL:
post:
summary: Party Event Callback
description: Triggered when a party screen event occurs.
operationId: partyEventCallback
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PartyCallbackEvent'
responses:
'200':
description: Callback accepted.
/webhooks/{id}:
get:
summary: Get a webhook subscription by ID.
description: Get details of your subscription to a specific webhook.
operationId: getWebhook
tags:
- Webhooks
parameters:
- name: id
in: path
description: Unique identifier for webhook subscription.
required: true
example: 944803b0-f1c2-4b28-91ce-8985b1f317a7
schema:
type: string
style: simple
responses:
'200':
description: Ok.
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookResponse'
examples:
GetWebhookByIdRes:
$ref: '#/components/examples/GetWebhookByIdRes'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'500':
$ref: '#/components/responses/500'
'503':
$ref: '#/components/responses/503'
post:
summary: Update a webhook by ID.
description: Add or Remove webhook subscriptions and change a webhook status to ACTIVE or INACTIVE
operationId: updateWebhook
tags:
- Webhooks
parameters:
- name: id
in: path
example: 944803b0-f1c2-4b28-91ce-8985b1f317a7
schema:
type: string
description: Unique identifier of the webhook to be updated
required: true
requestBody:
required: true
description: Update an existing webhook subscription.
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookUpdateRequest'
examples:
Update an existing webhook subscription with more events:
summary: Adding subscription(s) to a webhook
description: Request to add new subscription(s) to an existing webhook
value:
subscriptions:
- eventType: TRANSACTION_COMPLETED
- eventType: TRANSACTION_FAILED
status: ACTIVE
Update an existing webhook subscription to remove events:
summary: Removing subscription(s) from a webhook
description: Request to remove subscription(s) from a webhook
value:
subscriptions:
- eventType: TRANSACTION_FAILED
status: ACTIVE
Deactivate an existing webhook subscription:
summary: Changing status of a webhook
description: Request to change the status of a webhook
value:
subscriptions:
- eventType: TRANSACTION_COMPLETED
- eventType: TRANSACTION_FAILED
status: INACTIVE
responses:
'200':
description: OK.
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookResponse'
examples:
AddEventsToAWebhookSubscriptionRes:
$ref: '#/components/examples/AddSubscriptionsToAWebhookRes'
RemoveEventsToAWebhookSubscriptionRes:
$ref: '#/components/examples/RemoveSubscriptionsFromAWebhookRes'
ReplaceStatusOfAWebhookSubscriptionRes:
$ref: '#/components/examples/ChangeStatusOfAWebhookRes'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'500':
$ref: '#/components/responses/500'
'503':
$ref: '#/components/responses/503'
x-webhooks:
events:
post:
summary: Embedded Finance Event posted
tags:
- Webhooks
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookCallbackEvent'
responses:
'200':
description: Your server returns this code if it accepts the callback
components:
parameters:
pageNo:
name: page
in: query
description: Page Number
schema:
type: integer
default: 0
minimum: 0
maximum: 1000000
format: int32
required: false
pageSize:
name: limit
in: query
description: Number of records per page.
schema:
type: integer
minimum: 1
maximum: 25
default: 25
format: int32
required: false
schemas:
PageMetaData:
type: object
properties:
page:
type: integer
minimum: 0
format: int32
example: 1
description: 'Page Number.
'
limit:
type: integer
minimum: 0
format: int32
example: 30
description: 'Number of records per page.
'
total_items:
type: integer
minimum: 0
format: int32
example: 1
description: 'Total number of items.
'
SigningKey:
type: object
description: This returns the public key details used to decrypt the webhooks payload
properties:
publicKeyIdentifier:
type: string
description: Identifier for Public Key
example: 9d1f7465fa364f02bfffca49e6b0f158
publicKeyText:
type: string
description: public key that will be used to sign the webhook notification payloads, you will
need to store these three and fetch once the public key expires and rotate the keys
example: MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEY67BAtge8eY0yCyrhMONiCzHOtU2qbUkZE3I0whslqC5xpz/wArMGGjPxIDkHrLVCT4rFfxVDclydOySiCtOEw==
publicKeyExpirationDate:
type: string
description: Expiration date of the public key indicating the need for rotation
format: date-time
example: '2026-01-22T09:40:30.616Z'
EventTypeEnum:
type: string
enum:
- ACCOUNT_CLOSED
- ACCOUNT_CREATED
- ACCOUNT_FAILED
- ACCOUNT_OVERDRAWN
- ACCOUNT_RESTRICTION
- ACCOUNT_UPDATED
- ALLOCATION_ORDER_INSTRUCTION_NOTIFICATION
- ALLOCATION_ORDER_SETTLEMENT_NOTIFICATION
- CLIENT_ADD_INFO_FAILED
- CLIENT_ADD_INFO_REQUESTED
- CLIENT_ADD_INFO_VERIFIED
- CLIENT_OFFBOARDING_COMPLETED
- CLIENT_OFFBOARDING_INITIATED
- CLIENT_ONBOARDING
- CLIENT_ONBOARDING_COMPLETED
- DOCUMENT_GENERATED
- DOCUMENT_FAILED
- DOCUMENT_REQUESTED
- PARTY_NETWORK_SCREENING
- RECIPIENT_ACCOUNT_VALIDATION
- RECIPIENT_UPDATED
- REMITTANCE_STATUS
- TRANSACTION_CHANGE_REQUESTED
- TRANSACTION_COMPLETED
- TRANSACTION_FAILED
- THRESHOLD_LIMIT
- COUNTERPARTYENTITY
- PAYABLE
- PAYMENT
- INVOICE
- EXTERNALACCOUNT
- COUNTERPARTYUSER
description: The event types to be notified of.
example: ACCOUNT_CREATED
Subscription:
type: object
description: The webhooks you are subscribed to. Each subscription contains events about which you
are notified via HTTPS request to your pre-configured server URL.
required:
- eventType
properties:
eventType:
$ref: '#/components/schemas/EventTypeEnum'
WebhookResponse:
type: object
required:
- id
- subscriptions
- status
- createdAt
- updatedAt
properties:
id:
type: string
example: 944803b0-f1c2-4b28-91ce-8985b1f317a7
description: The unique identifier of this webhook
signingKey:
$ref: '#/components/schemas/SigningKey'
subscriptions:
type: array
items:
$ref: '#/components/schemas/Subscription'
minItems: 0
maxItems: 100
callbackURL:
type: string
description: The URL to which the webhook will send the event notifications
example: https://your-server.com/webhook
format: uri
status:
type: string
enum:
- ACTIVE
- INACTIVE
example: ACTIVE
description: The status of this webhook.
createdAt:
description: The date and time the webhook was created
type: string
format: date-time
example: '2017-07-21T17:32:28Z'
updatedAt:
description: The date and time the webhook was updated
type: string
format: date-time
example: '2017-07-21T17:32:28Z'
ListWebhookResponse:
type: object
required:
- metadata
- items
properties:
metadata:
$ref: '#/components/schemas/PageMetaData'
items:
type: array
nullable: false
description: List of webhooks you have created.
items:
$ref: '#/components/schemas/WebhookResponse'
minItems: 0
maxItems: 256
ApiErrorReasonV2:
type: object
description: Schema representing detailed reasons for an API error, including code, location, and
message.
required:
- message
properties:
code:
type: string
example: '11000'
description: Short code that identifies the error - publicly cataloged and documented
minLength: 0
maxLength: 5
location:
type: string
enum:
- BODY
- QUERY
- PATH
- HEADER
example: BODY
description: Part of the request which is responsible for the reason
field:
type: string
description: The location of the property or parameter in error
minLength: 0
maxLength: 512
message:
type: string
example: Client with ID 0031234567 does not exist.
description: Message describing the reason. This message can typically be displayed to your
platform's users, except in cases specified otherwise
minLength: 0
maxLength: 2048
ApiError:
type: object
required:
- title
- httpStatus
- error
properties:
title:
type: string
minLength: 1
maxLength: 512
description: Short humanly-readable title of the error
example: BAD REQUEST
httpStatus:
type: integer
minimum: 100
maximum: 599
format: int32
description: HTTP status code
example: 422
traceId:
type: string
minLength: 0
maxLength: 512
description: Internal assigned traced identifier
requestId:
type: string
minLength: 0
maxLength: 512
description: Client provided request identifier
context:
type: array
items:
$ref: '#/components/schemas/ApiErrorReasonV2'
description: Provides additional context and detail on the validation errors
minItems: 0
maxItems: 100
AuthorizationDetails:
type: object
description: This object holds additional authorization details to apply when sending webhook notifications.
properties:
clientSecret:
type: string
description: A confidential string known only to the application and the authorization server.
example: a1b2c3d4e5f6g7h8i9j0
clientId:
type: string
description: A public identifier for the application using Auth for authenticating the client.
example: '1234567890'
tokenEndpoint:
type: string
description: A reference to a web resource on the internet that specifies the location and mechanism
for the identity provider to fetch.
example: https://example.com/token
format: uri
SecurityPreferences:
type: object
description: Parent Object which holds information on security preferences for sending Webhook Notifications.
properties:
authorizationDetails:
$ref: '#/components/schemas/AuthorizationDetails'
headerFields:
description: Arbitrary key/value pairs that will be echoed back to the webhook subscribers as
headers in the HTTP webhook callback.
type: object
additionalProperties:
type: string
WebhookRequest:
description: Create a webhook
type: object
required:
- subscriptions
properties:
securityPreferences:
$ref: '#/components/schemas/SecurityPreferences'
subscriptions:
description: List of subscription items called subscription details
type: array
items:
$ref: '#/components/schemas/Subscription'
minItems: 0
maxItems: 100
callbackURL:
type: string
description: The URL to which the webhook will send the event notifications
example: https://your-server.com/webhook
format: uri
WebhookCallbackEventType:
type: string
description: Master list of all webhook callback event types. Resource-specific callback events
override this with a narrowed enum.
enum:
- ACCOUNT_CLOSED
- ACCOUNT_CREATED
- ACCOUNT_FAILED
- ACCOUNT_OVERDRAWN
- ACCOUNT_UPDATED
- ACCOUNT_RESTRICTION
- ALLOCATION_ORDER_INSTRUCTION_NOTIFICATION
- ALLOCATION_ORDER_SETTLEMENT_NOTIFICATION
- CLIENT_ONBOARDING
- DOCUMENT_GENERATED
- DOCUMENT_FAILED
- DOCUMENT_REQUESTED
- PARTY_NETWORK_SCREENING
- RECIPIENT_ACCOUNT_VALIDATION
- RECIPIENT_UPDATED
- REMITTANCE_STATUS
- TRANSACTION_CHANGE_REQUESTED
- TRANSACTION_COMPLETED
- TRANSACTION_FAILED
- THRESHOLD_LIMIT
ResourceObjectType:
type: string
enum:
- TRANSACTIONS
- CLIENTS
- PARTIES
- REMITTANCE
- ACCOUNTS
- RECIPIENTS
- DOCUMENTS
ApiErrorV2:
type: object
description: Schema representing a version 2 API error, including title, HTTP status, and additional
context.
required:
- title
properties:
title:
type: string
description: Short humanly-readable title of the error
example: BAD_REQUEST
minLength: 1
maxLength: 512
httpStatus:
type: integer
description: HTTP status code
minimum: 100
maximum: 599
format: int32
example: 400
traceId:
type: string
description: Internal assigned traced identifier
minLength: 0
maxLength: 512
requestId:
type: string
description: Client provided request identifier
minLength: 0
maxLength: 512
context:
type: array
items:
$ref: '#/components/schemas/ApiErrorReasonV2'
description: Provides additional context and detail on the validation errors
minItems: 0
maxItems: 100
WebhookCallbackEventBase:
type: object
required:
- eventId
- eventType
- resourceType
properties:
eventId:
type: string
description: Unique identifier of the event
example: '1863'
eventType:
$ref: '#/components/schemas/WebhookCallbackEventType'
resourceType:
$ref: '#/components/schemas/ResourceObjectType'
resource:
type: string
description: Json formatted string containing the notification details
example: '{"id": "UcMyVrUdXvZVhjUt","clientId": "0005191231","type": "ACH","debtorAccountId":
"10de11e98255479dbf43fd77ff55aa51","recipientId": null,"amount": "0.1","currency": "USD","status":
"REJECTED","transactionReferenceId": null,"paymentDate": "2023-11-23","ledgerBalance": "100.0"}'
error:
$ref: '#/components/schemas/ApiErrorV2'
CorrectedValue:
type: object
required:
- field
- value
properties:
field:
type: string
description: The field to be fixed
example: ACCTNUM
value:
type: string
description: The correct value for this field
example: '1271271448'
Context:
type: object
properties:
code:
type: string
description: The notification of change code.
message:
type: string
description: Description of incorrect fields to be fixed.
correctedValues:
type: array
minItems: 1
items:
$ref: '#/components/schemas/CorrectedValue'
ChangeDetails:
type: object
description: Details describing changes required to the recipient. This is only used when eventType
is `TRANSACTION_CHANGE_REQUESTED`.
required:
- title
- context
properties:
title:
type: string
default: Clearing Notification of Change
context:
$ref: '#/components/schemas/Context'
PaymentTypeResponseV3:
description: The transaction type indicates the nature of the transaction. Certain types cannot
be initiated through the API and, as a result, are excluded from the transaction request type
field. API and, as a result, are excluded from the transaction request type field.
type: string
nullable: false
enum:
- RTP
- WIRE
- ACH
- TRANSFER
- REVERSAL
- RETURN
- OTHER
- CARD
- FEE
- MISCELLANEOUS_CREDIT
- MISCELLANEOUS_DEBIT
example: ACH
OriginatingTransactionV3:
type: object
description: Details of the originating transaction for fees, returns, or linked transactions.
properties:
id:
type: string
description: Unique identifier of the originating transaction.
example: ff1b61523ea74c59b4ae606c6497cd52
type:
$ref: '#/components/schemas/PaymentTypeResponseV3'
TransactionPaymentPurpose:
description: The purpose of the payment
type: object
properties:
code:
description: Purpose of the payment in coded form. Must be between 1 and 4 characters.
type: string
minLength: 1
maxLength: 4
example: CASH
customCode:
description: Purpose of the payment in proprietary form. Must be between 1 and 35 characters.
type: string
minLength: 1
maxLength: 35
example: CASH INFLOW
CountryCode:
type: string
enum:
- US
description: Two letter country code based on ISO 3166 standard
example: US
TransactionCounterPartyAddressDetailsV3:
description: The address details of the counterparty.
type: object
required:
- city
- country
properties:
type:
description: The type of the counterparty address.
type: string
example: RESIDENTIAL_ADDRESS
buildingNumber:
description: Building name or number.
type: string
example: Apt 2E
streetName:
description: The street name of the counterparty address.
type: string
example: 90 Bedford Street
city:
description: Address city.
type: string
example: Springfield
country:
type: string
description: Two letter country code based on ISO 3166 standard, includes SEPA regions
example: US
countrySubDivision:
description: State or province code.
type: string
example: ND
postalCode:
description: Postal/ZIP code.
type: string
example: '58008'
TransactionCounterPartyIdentityDetailsV3:
description: Identity details for the counterparty.
type: object
properties:
idType:
type: string
enum:
- USCC
- ORGANIZATION_ID
- NATIONAL_ID
- TAX_ID
- SSN
description: Type of identification.
minLength: 1
example: TAX_ID
idValue:
type: string
description: Identification value.
example: '12345678901'
TransactionCounterPartyContactDetailsV3:
description: Contact details of the counterparty.
type: object
properties:
alternateName:
description: The alternate name of the counterparty.
type: string
example: Monica Downey
phoneNumber:
description: The phone number of the counterparty.
type: string
example: '+1234567890'
emailAddress:
description: The email address of the counterparty.
type: string
example: example@email.com
website:
description: The website of the counterparty.
type: string
example: https://www.example.com
TransactionCounterPartyDetailsV3:
description: The party details of the counterparty.
type: object
properties:
type:
description: The type of the counterparty.
type: string
example: INDIVIDUAL
name:
description: The name of the counterparty (individual or organization).
type: string
example: John Doe
address:
$ref: '#/components/schemas/TransactionCounterPartyAddressDetailsV3'
identities:
type: array
description: The Identity details for the counterparty.
items:
$ref: '#/components/schemas/TransactionCounterPartyIdentityDetailsV3'
minItems: 0
contacts:
$ref: '#/components/schemas/TransactionCounterPartyContactDetailsV3'
RoutingInformationTransactionType:
type: string
nullable: false
enum:
- ACH
- RTP
- WIRE
description: Type of transaction.
example: RTP
RoutingCodeType:
type: string
nullable: false
enum:
- USABA
description: Type of routing code.
example: USABA
RoutingInformationV3:
description: Routing information for the account.
type: object
properties:
routingNumber:
description: Routing number corresponding to the routing code type.
type: string
example: '541798298'
transactionType:
$ref: '#/components/schemas/RoutingInformationTransactionType'
routingCodeType:
$ref: '#/components/schemas/RoutingCodeType'
TransactionCounterPartyExternalAccountDetailsV3:
description: The external account details of the counterparty.
type: object
properties:
number:
description: The number of the counterparty account.
type: string
minLength: 1
example: 021009052
bankName:
description: The bank name of the counterparty external account.
type: string
minLength: 1
example: Bank of America
branchCode:
description: The branch code of the counterparty external account.
type: string
minLength: 1
example: '123456789'
routingInformation:
type: array
description: Routing information details of the counterparty external account.
items:
$ref: '#/components/schemas/RoutingInformationV3'
minItems: 0
currency:
description: The currency of the counterparty external account in ISO 4217 Alpha-3 Currency
Code format.
type: string
minLength: 1
maxLength: 3
example: USD
country:
description: The country of the counterparty external account. Two letter country code based
on ISO 3166 standard
type: string
minLength: 1
example: US
TransactionCounterPartyExternalAccountV3:
title: External Account
description: The external account of the counterparty
type: object
required:
- type
- externalAccount
properties:
type:
description: The type of the counterparty account
type: string
minLength: 1
externalAccount:
$ref: '#/components/schemas/TransactionCounterPartyExternalAccountDetailsV3'
TransactionCounterPartyRegisteredAccountDetailsV3:
description: The registered account details of the counterparty.
type: object
properties:
id:
description: The id of the counterparty account.
type: string
minLength: 1
example: d3371713f14e423f82065c9486ebe15b
name:
description: The display name of the registered account.
type: string
minLength: 1
example: Primary Checking
number:
description: Masked registered account number.
type: string
minLength: 1
example: '...4567'
ledgerBalance:
description: Ledger balance of the registered account after this transaction.
type: string
minLength: 1
example: '1000'
postingVersion:
description: Posting version of the registered account at the time of this transaction.
type: integer
example: 1
TransactionCounterPartyRegisteredAccountV3:
title: Registered Account
description: The registered account of the counterparty
type: object
required:
- type
- registeredAccount
properties:
type:
description: The type of the counterparty account
type: string
minLength: 1
default: REGISTERED_ACCOUNT
r
# --- truncated at 32 KB (68 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/jp-morgan-chase/refs/heads/main/openapi/jp-morgan-chase-webhooks-api-openapi.yml