Embedded Payments

Manage notifications

Events can occur asynchronously during banking and payment processes. You can use Embedded Payments webhooks to get real-time notifications about the following events:

Transaction events
Client events
Account events
Recipient events

Anatomy of a webhook

Each webhook consists of one or more subscriptions.

A subscription consists of the following:

eventType: representing a specific type of notification that you can choose to include in a webhook subscription.
CallbackURL: URL where the webhook notifications are sent.

If you have a requirement for signed payloads using an OAuth pattern, the subscription also consists of the following optional fields:

Clientid: representing the unique identifier that you generate for the Embedded Payments application.
Client Secret: A secret key that we use to generate a token, enabling you to sign the notifications.
Token URL: the endpoint where we obtain the OAuth 2.0 token.

You can add custom fields or unique identifiers in the webhook header for personalized data handling to meet specific business needs. In the JSON example, two pairs of flexible dictionary key-value pairs (e.g., "X-CustomKey1" <> CustomValue1) are defined and included in the HTTP webhook callback header.

Example implementation:

Example webhook implementation

Json

{ 
"securityPreferences": { 
"authorizationDetails":  { 
"headerFields": { 
"X-CustomKey1”: “CustomValue1", 
"X-CustomKey2”: “CustomValue2" 
      } 
    } 
  } 
}

Handling webhook notifications

Webhook notifications are sent to the URL you provide to J.P. Morgan. You must provide a response upon receipt of a notification.

The following is important information about handling webhook notifications:

It is expected that your server will respond with a success message (200 response) within three seconds of receiving a webhook notification.
If a success response is not received within this timeframe, the webhook is resent after a period of five minutes.
If no response is received by J.P. Morgan servers, the same message is sent up to a maximum of three times during a 72-hour period.

Webhook behavior - managing duplicates

You may occasionally receive duplicate notifications because J.P. Morgan servers often do not receive a 200 success response after sending the initial notification.

To check for duplicate notifications, check the eventId. If the IDs match, this is a duplicated or resent notification.

You must always respond with a 200 response, even to duplicated notifications.

To avoid passing the notification multiple times to your client, keep a log of notification eventIds.

Webhook behavior - event ordering

You may receive notifications of events that are out of sequence. For example, you may get information about some transactions sooner than others that were created at an earlier time.

Supported event types

You can receive notifications about the following event types:

TRANSACTION_COMPLETED: A transaction has completed.
TRANSACTION_CHANGE_REQUESTED: To proceed with this transaction, you must correct or change information related to the recipient’s bank account.
TRANSACTION_FAILED: The transaction has failed to process.
CLIENT_ONBOARDING: A client's onboarding status has changed.
ACCOUNT_CREATED: A new account has been successfully created.
ACCOUNT_CLOSED: The account has been closed.
ACCOUNT_OVERDRAWN: The account is in an overdrawn state and carries a negative balance.
RECIPIENT_ACCOUNT_VALIDATION: Your client's linked account requires validation through microdeposit check. This process has begun. Check the documentation for more details.
THRESHOLD_LIMIT: The platform is approaching their program-level negative balance limits, when they’ve exceeded their limits, and have restored negative balances.
RECIPIENT_UPDATED: The recipient's banking information has been updated after receiving a Notification of Change (NOC).

Create a webhook subscription

Use POST request to the /webhooks endpoint to create a webhook subscription. Provide the following parameters in your request:

subscriptions: one or more subscription events that should trigger alerts.

Example POST request:

Example POST request

Json

POST /webhooks HTTP/1.1  
Host: open-banking-way-server.com  
Content-Type: application/json  
  
{  
  "subscriptions": [  
    {  
        "eventType": "TRANSACTION_COMPLETED"  
    },  
    {  
        "eventType": "TRANSACTION_FAILED"  
    },  
    {  
        "eventType": "TRANSACTION_CHANGE_REQUESTED"  
    },  
    {  
        "eventType": "CLIENT_ONBOARDING"  
    },  
    {  
        "eventType": "RECIPIENT_ACCOUNT_VALIDATION"  
    }  
  ],  
"callbackURL": "https://your-server.com/webhook"  
}

In response, you should receive a 201 Created status to show that the webhook subscription is successfully created.

The response includes:

id: A unique identifier of the newly created subscription.
subscriptions: The list of subscription events.
status: The status is set to ACTIVE when the webhook subscription is created.
createdAt: The timestamp when the subscription was created.
updatedAt: The timestamp when the subscription was last updated.

Sample 201 response:

Sample 201 response

Json

{  
  "id": "944803b0-f1b2-4b28-91ce-8985b1f317a7",  
  "subscriptions": [  
    {  
      "eventType": "TRANSACTION_COMPLETED"  
    },  
    {  
        "eventType": "TRANSACTION_FAILED"  
    },  
    {  
      "eventType": "TRANSACTION_CHANGE_REQUESTED"  
    },  
    {  
      "eventType": "CLIENT_ONBOARDING"  
    },  
    {  
      "eventType": "RECIPIENT_ACCOUNT_VALIDATION"  
    }  
  ],  
  "status": "ACTIVE",  
  "callbackURL": "https://your-server.com/webhook",  
  "createdAt": "2023-10-02T12:18:450Z",  
  "updatedAt": "2023-10-02T12:18:450Z"  
}

Create a webhook subscription (OAuth)

Use POST request to the `/webhooks` endpoint to create a webhook subscription. Provide the following parameters in your request: 

Client ID: A unique identifier that you generate for the Embedded Payments webhook application. 
Client Secret: A secret key used to authenticate with your identity provider. 
Token URL: The endpoint where we can obtain an OAuth 2.0 token. 
Subscription: The specific events you want to subscribe to. 
HeaderFields: Additional header key-value pairs that need to be included as request headers in a webhook.

  Usage of headerFields 

 The headerFields are used to customize the HTTP headers of the webhook request. You can add any custom headers that your receiving server requires for processing the request. 

 Note: When configuring these headers, ensure that the keys are valid HTTP header names, which means they should not contain spaces and should follow standard naming conventions. 

Example POST request:

Create a webhook subscription (OAuth) POST request

Json

POST /webhooks HTTP/1.1  
Host: open-banking-way-server.com  
Content-Type: application/json  
 
{  
  "securityPreferences": {  
    "authorizationDetails": {  
      "clientSecret": "secret",  
      "clientId": "325432525",  
      "tokenEndpoint": "https://your-identity-provider.com/oauth2/token"  
    },  
    "headerFields": {  
      "X-CustomKey1”: “CustomValue1",  
      "X-CustomKey2”: “CustomValue2"  
    }  
  },  
  "callbackURL": "https://clienturl.com/api/v1/notification",  
  "subscriptions": [  
    {  
      "eventType": "TRANSACTION_COMPLETED"  
    }  
  ]  
}

In response, you should receive a 201 Created status to show that the webhook subscription is successfully created.

The response includes:

id: A unique identifier of the newly created subscription.
subscriptions: The list of subscription events.
status: The status is set to ACTIVE when the webhook subscription is created.
createdAt: The timestamp when the subscription was created.
updatedAt: The timestamp when the subscription was last updated.
publicKeyIdentifier: ID of the public-key being sent in the response. This will be referenced on the webhook notification headers. 
publicKeyText: The public key that will be used to sign the webhook notification payloads. 
publicKeyExpirationDate: Expiry date of the public key.

Sample 201 response:

Create a webhook subscription (OAuth) 201 response

Json

{  
  "id": "944803b0-f1c2-4b28-91ce-8985b1f317a7",  
  "subscriptions": [  
    {  
      "eventType": "TRANSACTION_COMPLETED"  
    }  
  ],  
  "signingKey": {  
    "publicKeyIdentifier": "string",  
    "publicKeyText": "string",  
    "publicKeyExpirationDate": "string"  
  },  
  "status": "ACTIVE",  
  "createdAt": "2023-10-29T17:59:13.699Z",  
  "updatedAt": "2023-10-29T17:59:13.699Z"  
}

Update a webhook

You can update an existing webhook resource by sending a payload that includes subscriptions and status changes you wish to make.

To update a webhook, send your request to POST:/webhooks/{id}. The id is the unique identifier of the existing webhook that you want to update.
To add a new subscription to an existing webhook, send the entire payload to POST:/webhooks/{id}. Your request must match the existing webhook resource with your additional subscription added to the subscriptions object in your request.
To remove a subscription to an existing webhook, send the entire payload to POST:/webhooks/{id}. Your request must match the existing webhook resource without the subscription you want to remove in the subscriptions object in your request.
To stop receiving nofications from a webhook, send the entire payload with the status updated. You can set the status to ACTIVE or INACTIVE.

Add a subscription to your webhook

To add a new subscription to an existing webhook, send the entire payload to POST:/webhooks/{id}. Your request must match the existing webhook resource with your additional subscription added to the subscriptions object in your request. The security preferences section is optional and used if you are using the OAuth pattern to receive signed payloads.

Original webhook subscriptions sample:

Original webhook subscriptions sample

Json

{ 
"securityPreferences": {  
  "authorizationDetails": {  
    "clientSecret": "secret",  
    "clientId": "325432525",  
    "tokenEndpoint": "https://your-identity-provider.com/oauth2/token"  
   },  
  "headerFields": {  
    "X-CustomKey1”: “CustomValue1",  
    "X-CustomKey2”: “CustomValue2"  
    },  
 }, 
  "subscriptions": [ 
    { 
      "eventType": "TRANSACTION_COMPLETED" 
    }, 
    { 
      "eventType": "TRANSACTION_FAILED" 
    }, 
    { 
      "eventType": "CLIENT_ONBOARDING" 
    } 
  ], 
"callbackURL": "https://clienturl.com/api/v1/notification", 
  "status": "ACTIVE" 
}

Update request to add a new eventType ACCOUNT_CREATED subscription:

Update request

Json

POST /webhooks/944803b0-f1b2-4b28-91ce-8985b1f317a7 HTTP/1.1 
Host: open-banking-way-server.com 
Content-Type: application/json 
{ 
"securityPreferences": {  
  "authorizationDetails": {  
    "clientSecret": "secret",  
    "clientId": "325432525",  
    "tokenEndpoint": "https://your-identity-provider.com/oauth2/token"  
   },  
  "headerFields": {  
    "X-CustomKey2”: “CustomValue2",  
    "X-CustomKey2”: “CustomValue2"  
    },  
 }, 
  "subscriptions": [ 
    { 
      "eventType": "TRANSACTION_COMPLETED" 
    }, 
    { 
      "eventType": "TRANSACTION_FAILED" 
    }, 
    { 
      "eventType": "CLIENT_ONBOARDING" 
    }, 
    { 
      "eventType": "ACCOUNT_CREATED" 
    } 
  ], 
"callbackURL": "https://clienturl.com/api/v1/notification", 
  "status": "ACTIVE", 
}

Response:

Sample response: eventType

Json

{
  "id": "944803b0-f1b2-4b28-91ce-8985b1f317a7",
  "subscriptions": [
    {
      "eventType": "TRANSACTION_COMPLETED"
    },
    {
      "eventType": "TRANSACTION_FAILED"
    },
    {
      "eventType": "CLIENT_ONBOARDING"
    },
    {
      "eventType": "ACCOUNT_CREATED"
    }
  ],
  "status": "ACTIVE",
  "createdAt": "2017-07-21T17:32:28Z",
  "updatedAt": "2017-07-30T10:45:15Z"
}

Remove a subscription

To stop receiving notifications, you can use the POST:/webhooks/:id with the one you want to keep in the `subscriptions` object. In the following example, you can see that CLIENT_ONBOARDING is going to be removed. The security preferences section is optional and used if you are using the OAuth pattern to receive signed payloads.

Original webhook subscriptions sample :

POST:/webhooks/:id request to change the status to INACTIVE

Json

POST:/webhooks/:id request to change the status to INACTIVE 
POST /webhooks/944803b0-f1b2-4b28-91ce-8985b1f317a7 HTTP/1.1 
Host: open-banking-way-server.com 
Content-Type: application/json 
{ 
"securityPreferences": {  
  "authorizationDetails": {  
    "clientSecret": "secret",  
    "clientId": "325432525",  
    "tokenEndpoint": "https://your-identity-provider.com/oauth2/token"  
   },  
  "headerFields": {  
    "X-CustomKey1”: “CustomValue1",  
    "X-CustomKey2”: “CustomValue2"  
    },  
 }, 
  "subscriptions": [ 
     { 
      "eventType": "TRANSACTION_COMPLETED" 
    }, 
    { 
      "eventType": "TRANSACTION_FAILED" 
    }, 
    { 
      "eventType": "CLIENT_ONBOARDING" 
    }, 
    { 
      "eventType": "ACCOUNT_CREATED" 
    } 
  ], 
"callbackURL": "https://clienturl.com/api/v1/notification", 
  "status": "INACTIVE", 
}

Update request to remove the eventType CLIENT_ONBOARDING:

Update request to remove the eventType CLIENT_ONBOARDING

Json

{
  "securityPreferences": {
    "authorizationDetails": {
      "clientSecret": "secret",
      "clientId": "325432525",
      "tokenEndpoint": "https://your-identity-provider.com/oauth2/token"
    },
    "headerFields": {
      "X-CustomKey1”: “CustomValue1",
      "X-CustomKey2”: “CustomValue2"
    },
  },
  "subscriptions": [{
      "eventType": "TRANSACTION_COMPLETED"
    },
    {
      "eventType": "TRANSACTION_FAILED"
    },
    {
      "eventType": "ACCOUNT_CREATED"
    }
  ],
  "callbackURL": "https://clienturl.com/api/v1/notification",
  "status": "ACTIVE"
}

Response:

Response

Json

{
  "id": "944803b0-f1c2-4b28-91ce-8985b1f317a7",
  "subscriptions": [
    {
      "eventType": "TRANSACTION_COMPLETED"
    },
    {
      "eventType": "TRANSACTION_FAILED"
    },
    {
      "eventType": "ACCOUNT_CREATED"
    }
  ],
  "status": "ACTIVE",
  "createdAt": "2017-07-21T17:32:28Z",
  "updatedAt": "2017-07-30T10:45:15Z"
}

Update the status of an existing webhook

To change the status of a webhook, send the entire payload with the status that must be set to your webhook. You can set the status to ACTIVE or INACTIVE.

Original ACTIVE subscription:

Original ACTIVE subscription

Json

{ 
"securityPreferences": {  
  "authorizationDetails": {  
    "clientSecret": "secret",  
    "clientId": "325432525",  
    "tokenEndpoint": "https://your-identity-provider.com/oauth2/token"  
   },  
  "headerFields": {  
    "X-CustomKey1”: “CustomValue1",  
    "X-CustomKey2”: “CustomValue2"  
    },  
 }, 
  "subscriptions": [ 
    { 
      "eventType": "TRANSACTION_COMPLETED" 
    }, 
    { 
      "eventType": "TRANSACTION_FAILED" 
    }, 
    { 
      "eventType": "ACCOUNT_CREATED" 
    } 
  ], 
"callbackURL": "https://clienturl.com/api/v1/notification", 
  "status": "ACTIVE" 
}

Request to set the status to INACTIVE:

Request to set the status to INACTIVE

Json

Host: open-banking-way-server.com 
Content-Type: application/json 
{ 
"securityPreferences": {  
  "authorizationDetails": {  
    "clientSecret": "secret",  
    "clientId": "325432525",  
    "tokenEndpoint": "https://your-identity-provider.com/oauth2/token"  
   },  
  "headerFields": {  
    "X-CustomKey1”: “CustomValue1",  
    "X-CustomKey2”: “CustomValue2"  
    },  
 }, 
  "subscriptions": [ 
    { 
      "eventType": "TRANSACTION_COMPLETED" 
    }, 
    { 
      "eventType": "TRANSACTION_FAILED" 
    }, 
    { 
      "eventType": "ACCOUNT_CREATED" 
    } 
  ], 
"callbackURL": "https://clienturl.com/api/v1/notification", 
  "status": "INACTIVE" 
}

Success response 200 OK:

Success Response 200 OK

Json

{
  "subscriptions": [
    {
      "eventType": "TRANSACTION_COMPLETED"
    },
    {
      "eventType": "TRANSACTION_FAILED"
    },
    {
      "eventType": "ACCOUNT_CREATED"
    }
  ],
  "status": "INACTIVE",
  "createdAt": "2017-07-21T17:32:28Z",
  "updatedAt": "2017-07-30T10:45:15Z"
}

Get a list of your webhook subscriptions

Use the GET:/webhooks endpoint to list all of your webhooks subscriptions.

Sample request:

GET:/webhooks

Curl

curl -X 'GET' \
  'https://base-url/api/v1/eb/webhooks' \
  -H 'accept: application/json'

Sample response:

Sample response

Json

{
  "metadata": {
    "page": 0,
    "limit": 25,
    "total_items": 2
  },
  "items": [
    {
      "id": "944803b0-f1c2-4b28-91ce-8985b1f317a7",
      "subscriptions": [
          {
            "eventType": "TRANSACTION_COMPLETED"
          },
          {
            "eventType": "TRANSACTION_FAILED"
          },
          {
            "eventType": "ACCOUNT_CREATED"
          }
      ],
      "status": "ACTIVE",
      "createdAt": "2017-07-21T17:32:28Z",
      "updatedAt": "2017-07-21T17:32:28Z"
    },
    {
      "id": "878803b0-f1c2-4b28-91ce-8985b1f36715",
      "subscriptions": [
        {
          "eventType": "ACCOUNT_CLOSED"
        }
      ],
      "status": "ACTIVE",
      "createdAt": "2017-07-21T17:40:28Z",
      "updatedAt": "2017-07-21T17:40:28Z"
    }
  ]
}

See a specific webhook subscription

Use GET:/webhooks/:id to see a specific webhook subscription.

Sample request:

GET:/webhooks/:id

Curl

curl -X 'GET' \
  'https://base-url/api/v1/eb/webhooks/UUID' \
  -H 'accept: application/json'

Sample response:

Sample response

Json

{
  "id": "944803b0-f1c2-4b28-91ce-8985b1f317a7",
  "subscriptions": [
    {
      "eventType": "TRANSACTION_COMPLETED"
    },
    {
      "eventType": "TRANSACTION_FAILED"
    },
    {
      "eventType": "ACCOUNT_CREATED"
    }
  ],
  "status": "ACTIVE",
  "createdAt": "2017-07-21T17:32:28Z",
  "updatedAt": "2017-07-21T17:32:28Z"
}

Next steps

Take a look at sample webhook notification payloads.