Reference documentation for webhooks
Webhooks are designed for customers to manage their subscriptions and receive notifications about events. Events are triggered by the system to signal a change has occurred after a certain action is performed. By receiving notifications customers are able to react accordingly.
For example, customer can provide an endpoint in order to receive notification on direct bank transfer creation. Then instead of having to poll whether creation succeeded or not, it will be notified when direct bank data transfer successfully completes or fails.
The following list contains the event and primary ID field names as used when subscribing to webhooks and in the webhooks message, and short descriptions of the events. Currently, webhooks are mostly used for endpoints which require 2-factor authentication.
The search functionality can be utilized to search by category, event, primary ID, or description.
Category | Event | Primary ID | Description |
---|
Every webhook is a composition of URL, authentication, and subscriptions, whereas - URL: The address of the endpoint the notification is sent to. - Authentication: An authenticate method used to authenticate the messages it sends to the URL - Subscriptions: A list for event types the URL will be notified of.
Please read Webhooks section in complete API reference for more details.
The payload for push notification has the following general overview:
{
"eventType": "string",
"webhookUuid": "string",
"payload": "object",
"meta": {
"version": "string",
"timestamp": "long",
}
}
Let's say request for invoice payment was created for invoice with ID = 1* and transaction identifier = 123456789** was assigned. Then the transaction was confirmed, and now we would like to know if payment was created successfully or not.
A correct Webhook subscription for INVOICE_PAYMENT_CREATED event was created by POST /webhooks, like for example:
{
"url": "www.customerurl.com/myinvoicepaymentcreated",
"authenticationType": "HMAC"
"authenticationMeta": {
"sharedSecret": "1234567890",
"hashFunction": "SHA512"
}
"subscriptions": [
"INVOICE_PAYMENT_CREATED"
]
}
and the webhook uuid was generated and provided with value 0example-uuid-0000-0000-000000000000.
A result will be sent to example URL, registered for the given event. - Example - successful case:
{
"eventType": "INVOICE_PAYMENT_CREATED",
"webhookUuid": "0example-uuid-0000-0000-000000000000",
"payload": {
"transactionIdentifier": "123456789",
"transactions": [
{
"paymentId": 123, // Identifier of created payment, provided by the application
"invoiceId": 1
}
]
},
"meta": {
"version": "latest"
"timestamp": "1672542755"
}
}
Note that payload in this case contains transaction identifier and body of invoice payment response. Please check InvoicePaymentSummaries schema in complete API reference
{
"eventType": "INVOICE_PAYMENT_CREATED",
"webhookUuid": "0example-uuid-0000-0000-000000000000",
"payload": {
"transactionIdentifier": "123456789",
"errors": [
{
"status": 400,
"field": "payerBankAccount",
"message": "INVALID_PAYER_BANK_ACCOUNT"
}
]
},
"meta": {
"version": "latest"
"timestamp": "1672542755"
}
}
Analogical payload information are returned by running confirm endpoint PUT /payments/123456789/confirm
{
"transactions": [
{
"paymentId": 123,
"invoiceId": 1
}
]
}
{
"errors": [
{
"status": 400,
"field": "payerBankAccount",
"message": "INVALID_PAYER_BANK_ACCOUNT"
}
]
}