API Explorer

v5.0.0 (564 APIs)

Bank
Accounts
Views
Counterparties
Transactions

Create an Account Webhook

Create an Account Webhook

Webhooks are used to call external URLs when certain events happen.

Account Webhooks focus on events around accounts.

For instance, a webhook could be used to notify an external service if a balance changes on an account.

This functionality is work in progress! Please note that only implemented trigger is: OnBalanceChange

Authentication is Mandatory

URL Parameters:

BANK_ID: gh.29.uk

JSON request body fields:

account_id: 8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0

http_method: GET

http_protocol:

is_active: false

trigger_name:

url: http://www.example.com/id-docs/123/image.png

JSON response body fields:

account_id: 8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0

account_webhook_id:

bank_id: gh.29.uk

created_by_user_id:

http_method: GET

http_protocol:

is_active: false

trigger_name:

url: http://www.example.com/id-docs/123/image.png

Typical Successful Response:

								
									
{ "account_webhook_id":"613c83ea-80f9-4560-8404-b9cd4ec42a7f", "bank_id":"gh.29.uk", "account_id":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0", "trigger_name":"OnBalanceChange", "url":"https://localhost.openbankproject.com", "http_method":"POST", "http_protocol":"HTTP/1.1", "created_by_user_id":"9ca9a7e4-6d02-40e3-a129-0b2bf89de9b1", "is_active":true }
Required Roles:
  • CanCreateWebhook - Please login to request this Role
Validations:
  • Required JSON Validation: No
  • Allowed Authentication Types: Not set
Possible Errors:
  • OBP-50000: Unknown Error.
  • OBP-20001: User not logged in. Authentication is required!
  • OBP-20006: User is missing one or more roles:
Connector Methods:
Version: OBPv3.1.0, function_name: by createAccountWebhook, operation_id: OBPv3.1.0-createAccountWebhook Tags: Webhook, Bank,

Create bank level Account Notification Webhook

Create a notification Webhook that will fire for all accounts on the specified Bank.

Webhooks are used to call external web services when certain events happen.

For instance, a webhook can be used to notify an external service if a transaction is created on an account.

When an account notification webhook fires it will POST to the URL you specify during the creation of the webhook.

Inside the payload you will find account_id and transaction_id and also user_ids and customer_ids of the Users / Customers linked to the Account.

The webhook will POST the following structure to your service:

{
"event_name": "OnCreateTransaction",
"event_id": "9ca9a7e4-6d02-40e3-a129-0b2bf89de9b1",
"bank_id": "gh.29.uk",
"account_id": "8ca9a7e4-6d02-40e3-a129-0b2bf89de9b1",
"transaction_id": "7ca9a7e4-6d02-40e3-a129-0b2bf89de9b1",
"related_entities": [
{
"user_id": "8ca9a7e4-6d02-40e3-a129-0b2bf89de9b1",
"customer_ids": ["3ca9a7e4-6d02-40e3-a129-0b2bf89de9b1"]
}
]
}

Thus, your service should accept the above POST body structure.

In this way, your web service can be informed about an event on an account and act accordingly.

Further information about the account, transaction or related entities can then be retrieved using the standard REST APIs.

Authentication is Mandatory

URL Parameters:

BANK_ID: gh.29.uk

JSON request body fields:

http_method: GET

http_protocol:

url: http://www.example.com/id-docs/123/image.png

JSON response body fields:

bank_id: gh.29.uk

created_by_user_id:

http_method: GET

http_protocol:

trigger_name:

url: http://www.example.com/id-docs/123/image.png

webhook_id: webhook_id

Typical Successful Response:

								
									
{ "webhook_id":"fc23a7e2-7dd2-4bdf-a0b4-ae31232a4762", "bank_id":"gh.29.uk", "trigger_name":"OnCreateTransaction", "url":"https://localhost.openbankproject.com", "http_method":"POST", "http_protocol":"HTTP/1.1", "created_by_user_id":"9ca9a7e4-6d02-40e3-a129-0b2bf89de9b1" }
Required Roles:
  • CanCreateAccountNotificationWebhookAtOneBank - Please login to request this Role
Validations:
  • Required JSON Validation: No
  • Allowed Authentication Types: Not set
Possible Errors:
  • OBP-20001: User not logged in. Authentication is required!
  • OBP-30001: Bank not found. Please specify a valid value for BANK_ID.
  • OBP-50000: Unknown Error.
  • OBP-20006: User is missing one or more roles:
Connector Methods:
Version: OBPv4.0.0, function_name: by createBankAccountNotificationWebhook, operation_id: OBPv4.0.0-createBankAccountNotificationWebhook Tags: Webhook, Bank,

Create system level Account Notification Webhook

Create a notification Webhook that will fire for all accounts on the system.

Webhooks are used to call external web services when certain events happen.

For instance, a webhook can be used to notify an external service if a transaction is created on an account.

When an account notification webhook fires it will POST to the URL you specify during the creation of the webhook.

Inside the payload you will find account_id and transaction_id and also user_ids and customer_ids of the Users / Customers linked to the Account.

The webhook will POST the following structure to your service:

{
"event_name": "OnCreateTransaction",
"event_id": "9ca9a7e4-6d02-40e3-a129-0b2bf89de9b1",
"bank_id": "gh.29.uk",
"account_id": "8ca9a7e4-6d02-40e3-a129-0b2bf89de9b1",
"transaction_id": "7ca9a7e4-6d02-40e3-a129-0b2bf89de9b1",
"related_entities": [
{
"user_id": "8ca9a7e4-6d02-40e3-a129-0b2bf89de9b1",
"customer_ids": ["3ca9a7e4-6d02-40e3-a129-0b2bf89de9b1"]
}
]
}

Thus, your service should accept the above POST body structure.

In this way, your web service can be informed about an event on an account and act accordingly.

Further information about the account, transaction or related entities can then be retrieved using the standard REST APIs.

Authentication is Mandatory

JSON request body fields:

http_method: GET

http_protocol:

url: http://www.example.com/id-docs/123/image.png

JSON response body fields:

created_by_user_id:

http_method: GET

http_protocol:

trigger_name:

url: http://www.example.com/id-docs/123/image.png

webhook_id: webhook_id

Typical Successful Response:

								
									
{ "webhook_id":"fc23a7e2-7dd2-4bdf-a0b4-ae31232a4762", "trigger_name":"OnCreateTransaction", "url":"https://localhost.openbankproject.com", "http_method":"POST", "http_protocol":"HTTP/1.1", "created_by_user_id":"9ca9a7e4-6d02-40e3-a129-0b2bf89de9b1" }
Required Roles:
  • CanCreateSystemAccountNotificationWebhook - Please login to request this Role
Validations:
  • Required JSON Validation: No
  • Allowed Authentication Types: Not set
Possible Errors:
  • OBP-50000: Unknown Error.
  • OBP-20001: User not logged in. Authentication is required!
  • OBP-20006: User is missing one or more roles:
Connector Methods:
Version: OBPv4.0.0, function_name: by createSystemAccountNotificationWebhook, operation_id: OBPv4.0.0-createSystemAccountNotificationWebhook Tags: Webhook, Bank,

Enable/Disable an Account Webhook

Enable/Disable an Account Webhook

Webhooks are used to call external URLs when certain events happen.

Account Webhooks focus on events around accounts.

For instance, a webhook could be used to notify an external service if a balance changes on an account.

This functionality is work in progress! Please note that only implemented trigger is: OnBalanceChange

Authentication is Mandatory

URL Parameters:

BANK_ID: gh.29.uk

JSON response body fields:

account_id: 8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0

account_webhook_id:

bank_id: gh.29.uk

created_by_user_id:

http_method: GET

http_protocol:

is_active: false

trigger_name:

url: http://www.example.com/id-docs/123/image.png

Typical Successful Response:

								
									
{ "account_webhook_id":"613c83ea-80f9-4560-8404-b9cd4ec42a7f", "bank_id":"gh.29.uk", "account_id":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0", "trigger_name":"OnBalanceChange", "url":"https://localhost.openbankproject.com", "http_method":"POST", "http_protocol":"HTTP/1.1", "created_by_user_id":"9ca9a7e4-6d02-40e3-a129-0b2bf89de9b1", "is_active":true }
Required Roles:
  • CanUpdateWebhook - Please login to request this Role
Validations:
  • Required JSON Validation: No
  • Allowed Authentication Types: Not set
Possible Errors:
  • OBP-50000: Unknown Error.
  • OBP-20001: User not logged in. Authentication is required!
  • OBP-20006: User is missing one or more roles:
Connector Methods:
Version: OBPv3.1.0, function_name: by enableDisableAccountWebhook, operation_id: OBPv3.1.0-enableDisableAccountWebhook Tags: Webhook, Bank,

Get Account Webhooks

Get Account Webhooks.

Possible custom URL parameters for pagination:

Possible custom url parameters for pagination:

  • limit=NUMBER ==> default value: 50
  • offset=NUMBER ==> default value: 0

eg1:?limit=100&offset=0

  • sort_direction=ASC/DESC ==> default value: DESC.

eg2:?limit=100&offset=0&sort_direction=ASC

  • account_id=STRING (if null ignore)
  • user_id=STRING (if null ignore)

Authentication is Mandatory

URL Parameters:

BANK_ID: gh.29.uk

JSON response body fields:

account_id: 8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0

account_webhook_id:

bank_id: gh.29.uk

created_by_user_id:

http_method: GET

http_protocol:

is_active: false

trigger_name:

url: http://www.example.com/id-docs/123/image.png

web_hooks:

Typical Successful Response:

								
									
{ "web_hooks":[{ "account_webhook_id":"613c83ea-80f9-4560-8404-b9cd4ec42a7f", "bank_id":"gh.29.uk", "account_id":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0", "trigger_name":"OnBalanceChange", "url":"https://localhost.openbankproject.com", "http_method":"POST", "http_protocol":"HTTP/1.1", "created_by_user_id":"9ca9a7e4-6d02-40e3-a129-0b2bf89de9b1", "is_active":true }] }
Required Roles:
  • CanGetWebhooks - Please login to request this Role
Validations:
  • Required JSON Validation: No
  • Allowed Authentication Types: Not set
Possible Errors:
  • OBP-20001: User not logged in. Authentication is required!
  • OBP-20006: User is missing one or more roles:
  • OBP-50000: Unknown Error.
Connector Methods:
Version: OBPv3.1.0, function_name: by getAccountWebhooks, operation_id: OBPv3.1.0-getAccountWebhooks Tags: Webhook, Bank,