{"swagger":"2.0","info":{"title":"Open Bank Project API","description":"An Open Source API for Banks. (c) TESOBE GmbH. 2011 - 2024. Licensed under the AGPL and commercial licences.","contact":{"name":"TESOBE GmbH. / Open Bank Project","url":"https://openbankproject.com","email":"contact@tesobe.com"},"version":"v4.0.0"},"host":"apisandbox.openbankproject.com","basePath":"/","schemes":["http","https"],"securityDefinitions":{"directLogin":{"type":"apiKey","description":"https://github.com/OpenBankProject/OBP-API/wiki/Direct-Login","in":"header","name":"Authorization"},"gatewayLogin":{"type":"apiKey","description":"https://github.com/OpenBankProject/OBP-API/wiki/Gateway-Login","in":"header","name":"Authorization"}},"security":[{"directLogin":[],"gatewayLogin":[]}],"paths":{"/obp/v4.0.0/banks/{BANK_ID}/account-web-hooks":{"post":{"tags":["Webhook","Bank"],"summary":"Create an Account Webhook","security":[{"directLogin":[],"gatewayLogin":[]}],"description":"
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
","operationId":"createAccountWebhook","parameters":[{"in":"body","name":"body","description":"AccountWebhookPostJson object that needs to be added.","required":true,"schema":{"$ref":"#/definitions/AccountWebhookPostJson"}},{"in":"path","name":"BANK_ID","description":"The bank id","required":true,"type":"string"}],"responses":{"201":{"description":"Success","schema":{"$ref":"#/definitions/AccountWebhookJson"}},"400":{"description":"Error","schema":{"$ref":"#/definitions/ErrorUnknownError"}}}},"put":{"tags":["Webhook","Bank"],"summary":"Enable/Disable an Account Webhook","security":[{"directLogin":[],"gatewayLogin":[]}],"description":"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
","operationId":"enableDisableAccountWebhook","parameters":[{"in":"body","name":"body","description":"AccountWebhookPutJson object that needs to be added.","required":true,"schema":{"$ref":"#/definitions/AccountWebhookPutJson"}},{"in":"path","name":"BANK_ID","description":"The bank id","required":true,"type":"string"}],"responses":{"200":{"description":"Success","schema":{"$ref":"#/definitions/AccountWebhookJson"}},"400":{"description":"Error","schema":{"$ref":"#/definitions/ErrorUnknownError"}}}}},"/obp/v4.0.0/banks/{BANK_ID}/web-hooks/account/notifications/on-create-transaction":{"post":{"tags":["Webhook","Bank"],"summary":"Create bank level Account Notification Webhook","security":[{"directLogin":[],"gatewayLogin":[]}],"description":"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
","operationId":"createBankAccountNotificationWebhook","parameters":[{"in":"body","name":"body","description":"AccountNotificationWebhookPostJson object that needs to be added.","required":true,"schema":{"$ref":"#/definitions/AccountNotificationWebhookPostJson"}},{"in":"path","name":"BANK_ID","description":"The bank id","required":true,"type":"string"}],"responses":{"201":{"description":"Success","schema":{"$ref":"#/definitions/BankAccountNotificationWebhookJson"}},"400":{"description":"Error","schema":{"$ref":"#/definitions/ErrorUserNotLoggedIn"}}}}},"/obp/v4.0.0/management/banks/{BANK_ID}/account-web-hooks":{"get":{"tags":["Webhook","Bank"],"summary":"Get Account Webhooks","security":[{"directLogin":[],"gatewayLogin":[]}],"description":"Get Account Webhooks.
Possible custom URL parameters for pagination:
Possible custom url parameters for pagination:
eg1:?limit=100&offset=0
eg2:?limit=100&offset=0&sort_direction=ASC
Authentication is Mandatory
","operationId":"getAccountWebhooks","parameters":[{"in":"path","name":"BANK_ID","description":"The bank id","required":true,"type":"string"}],"responses":{"200":{"description":"Success","schema":{"$ref":"#/definitions/AccountWebhooksJson"}},"400":{"description":"Error","schema":{"$ref":"#/definitions/ErrorUserNotLoggedIn"}}}}},"/obp/v4.0.0/web-hooks/account/notifications/on-create-transaction":{"post":{"tags":["Webhook","Bank"],"summary":"Create system level Account Notification Webhook","security":[{"directLogin":[],"gatewayLogin":[]}],"description":"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
","operationId":"createSystemAccountNotificationWebhook","parameters":[{"in":"body","name":"body","description":"AccountNotificationWebhookPostJson object that needs to be added.","required":true,"schema":{"$ref":"#/definitions/AccountNotificationWebhookPostJson"}}],"responses":{"201":{"description":"Success","schema":{"$ref":"#/definitions/SystemAccountNotificationWebhookJson"}},"400":{"description":"Error","schema":{"$ref":"#/definitions/ErrorUnknownError"}}}}}},"definitions":{"ErrorUserNotLoggedIn":{"properties":{"message":{"type":"string","example":"OBP-20001: User not logged in. Authentication is required!"}}},"ErrorUnknownError":{"properties":{"message":{"type":"string","example":"OBP-50000: Unknown Error."}}},"BankAccountNotificationWebhookJson":{"required":["created_by_user_id","url","trigger_name","http_protocol","http_method","bank_id","webhook_id"],"properties":{"created_by_user_id":{"type":"string","example":"9ca9a7e4-6d02-40e3-a129-0b2bf89de9b1"},"url":{"type":"string","example":"https://localhost.openbankproject.com"},"trigger_name":{"type":"string","example":"OnCreateTransaction"},"http_protocol":{"type":"string","example":"HTTP/1.1"},"http_method":{"type":"string","example":"POST"},"bank_id":{"type":"string","example":"gh.29.uk"},"webhook_id":{"type":"string","example":"fc23a7e2-7dd2-4bdf-a0b4-ae31232a4762"}}},"AccountWebhookJson":{"required":["created_by_user_id","is_active","url","trigger_name","http_protocol","account_webhook_id","http_method","bank_id","account_id"],"properties":{"created_by_user_id":{"type":"string","example":"9ca9a7e4-6d02-40e3-a129-0b2bf89de9b1"},"is_active":{"type":"boolean","example":"true"},"url":{"type":"string","example":"https://localhost.openbankproject.com"},"trigger_name":{"type":"string","example":"OnBalanceChange"},"http_protocol":{"type":"string","example":"HTTP/1.1"},"account_webhook_id":{"type":"string","example":"613c83ea-80f9-4560-8404-b9cd4ec42a7f"},"http_method":{"type":"string","example":"POST"},"bank_id":{"type":"string","example":"gh.29.uk"},"account_id":{"type":"string","example":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0"}}},"AccountNotificationWebhookPostJson":{"required":["url","http_method","http_protocol"],"properties":{"url":{"type":"string","example":"https://localhost.openbankproject.com"},"http_method":{"type":"string","example":"POST"},"http_protocol":{"type":"string","example":"HTTP/1.1"}}},"AccountWebhookPutJson":{"required":["account_webhook_id","is_active"],"properties":{"account_webhook_id":{"type":"string","example":"fc23a7e2-7dd2-4bdf-a0b4-ae31232a4762"},"is_active":{"type":"string","example":"true"}}},"AccountWebhookPostJson":{"required":["is_active","url","trigger_name","http_protocol","http_method","account_id"],"properties":{"is_active":{"type":"string","example":"true"},"url":{"type":"string","example":"https://localhost.openbankproject.com"},"trigger_name":{"type":"string","example":"OnBalanceChange"},"http_protocol":{"type":"string","example":"HTTP/1.1"},"http_method":{"type":"string","example":"POST"},"account_id":{"type":"string","example":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0"}}},"AccountWebhooksJson":{"required":["web_hooks"],"properties":{"web_hooks":{"type":"array","items":{"$ref":"#/definitions/AccountWebhookJson"}}}},"SystemAccountNotificationWebhookJson":{"required":["created_by_user_id","url","trigger_name","http_protocol","http_method","webhook_id"],"properties":{"created_by_user_id":{"type":"string","example":"9ca9a7e4-6d02-40e3-a129-0b2bf89de9b1"},"url":{"type":"string","example":"https://localhost.openbankproject.com"},"trigger_name":{"type":"string","example":"OnCreateTransaction"},"http_protocol":{"type":"string","example":"HTTP/1.1"},"http_method":{"type":"string","example":"POST"},"webhook_id":{"type":"string","example":"fc23a7e2-7dd2-4bdf-a0b4-ae31232a4762"}}}}}