Webhooks Reference

Webhooks reference

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.

List of supported event types

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.

Webhooks management

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.

Pushed notifications

The payload for push notification has the following general overview:

{
   "eventType": "string",
   "webhookUuid": "string",
   "payload": "object",
   "meta": {
      "version": "string",
      "timestamp": "long",
   }
}

• eventType: The type of the event the notification is about
• webhookUuid: The UUID of the registered webhook
• payload: The actual payload, which belongs to the reported eventType. For 2-factor authenticated endpoints it contains transaction identifier and body response returned by PUT /confirm endpoint
• meta: Additional information about the notification itself.
• version: Indicate the API version, to know which version of the webhook notification DTO it is, in case the Notification structure is changed
• timestamp: Indicate an Epoch timestamp when the notification event has been generated.

Example of a use case

1. POST /payments request is sent to pay an invoice
2. System validates the request
3. If it passes, user receives a 2-factor authentication transaction identifier
4. User confirms the transaction in confirmation application (Finago Key or Procountor Key)
5. System generates invoice payment
6. User can receive result of the transaction in 2 ways:
   • via Webhook notification. By adding webhook subscription URL for type INVOICE_PAYMENT_CREATED, notification is sent directly to this URL
   • by calling PUT /payments/{transactionIdentifier}/confirm

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.

Receive pushed notification

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

• Example - when validation fails:

{
    "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"
    }
}

Response received by calling confirm endpoint

Analogical payload information are returned by running confirm endpoint PUT /payments/123456789/confirm

• Example - successful case:

{
    "transactions": [
        {
            "paymentId": 123,
            "invoiceId": 1
        }
    ]
}

• Example - when validation fails:

{
    "errors": [
        {
            "status": 400,
            "field": "payerBankAccount",
            "message": "INVALID_PAYER_BANK_ACCOUNT"
        }
    ]
}