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 where:
  • 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.

Webhook push notifications

Example of payload for push notification:

{
   "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 (Procountor Key)
5. System generates invoice payment
6. User can receive result of the transaction in 2 ways:
   • via Webhook push 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 result via Webhook push notification

Precondition

To receive push notification via Webhook, user needs to first subscribe to the event it's interested in. Suppose user has already subscribed to INVOICE_PAYMENT_CREATED event by calling POST /webhooks with the following request body:

{
    "url": "www.customerurl.com/myinvoicepaymentcreated",
    "authenticationType": "HMAC"  
    "authenticationMeta": {
        "sharedSecret": "1234567890",
        "hashFunction": "SHA512"
    }
    "subscriptions": [
        "INVOICE_PAYMENT_CREATED"
    ]
}

And API has sent a successful response with webhook uuid 0example-uuid-0000-0000-000000000000.

Example: successful case

Result is sent to the provided URL for the registered event.

{
    "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 the invoice payment response. Please check InvoicePaymentSummaries schema in complete API reference

Example: when validation fails

Result is sent to the provided URL for the registered event.

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

Receive result by calling confirm endpoint

Instead of using Webhook, user calls 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"
        }
    ]
}