Webhooks APIs

Modification notifications are triggered when certain fields within some objects change. The list of objects and fields, the change of which will trigger an event and send a notification, includes:

• Recurring: 'PaymentOption.isActive', 'Subscription.status'
• Management: 'Terminal.status', 'MerchantAccountGroup.isRemittanceHoldEnabledModified'

Webhook notifications can be activated in case of a change in the value of one of the specified fields.
The fieldName field will indicate the name of the field that has been changed.
The oldValue field will indicate the value that existed before the changes.
The newValue field will indicate the value that was set after the changes.

In the system, there are two types of references to objects:

• Fields ending with Id contain unique internal identifiers generated by the Gateway system.
• Fields ending with Code contain external identifiers provided and defined by the integrator at the stage of creating a specific object. Using these codes can be convenient for quickly determining which object a webhook relates to in the system receiving these notifications (in the integrator's system). However, for this process to be efficient, it's important to specify these values when creating transactions and objects.

For example, when a 'sale' transaction is executed through the Processing API, the system automatically assigns it a value that is returned in the transactionId field. But if the integrator wants to also store this transaction in their system and has a separate ID for this record, they can pass it as transactionCode. Then, if a Webhook notification is sent regarding this transaction, it will contain both the transactionId generated by Gateway and the transactionCode provided by the integrator. This functionality allows the integrator to quickly find in their system the object undergoing changes, using their own ID that they passed as transactionCode.

This mechanism also works for all other objects, such as Merchant, Customer, Account, Payment Option, Subscription, etc.

Generally, notifications are delivered with a small delay after the occurrence of an event, which can vary from a few seconds to several minutes. However, there are risks that at the time of delivery the webhook page may be temporarily unavailable for various reasons, such as network issues or problems with the server on which the page is hosted.

To ensure reliable delivery, the gateway includes a re-delivery mechanism. This mechanism ensures delivery by reattempting resending notifications over some time.
The gateway expects a response from the page receiving the notification. In order for the re-delivery mechanism to work correctly, every page used to consume webhook notifications is expected to provide confirmation once it has successfully processed the notification. By doing so it notifies the re-delivery mechanism that know subsequent delivery of this event is necessary.
Consequently, if the confirmation is not provided, the re-delivery mechanism will continue to resend this notification on the schedule defined below.

For the page to confirm delivery, it must respond to the gateway with the following information. Each notification that is delivered has a unique notification ID, which is included in the format of the notification message. The page that receives the notification should reply back to the gateway with the value of this notification ID in the format {notificationId: value}. For instance, if you receive a notification with notificationId=12345, you will have to respond with {“notificationId”: “12345”}.
The re-delivery mechanism ensures automatic redelivery of notifications in case the confirmation response was not received by the gateway.
Retry attempts are performed based on the schedule below.

If an event is not processed successfully on the first attempt:

• The second notification is sent 5 minutes after the first failed attempt.
• The third notification is sent 15 minutes after the second failed attempt.
• The fourth notification is sent 60 minutes after the third failed attempt.
• The fifth notification is sent 24 hours after the fourth failed attempt.
• If the fifth attempt fails, the notification status is changed to "Failed" and no further redelivery will take place.

To optimize the process of parsing and handling notifications for the integrator, the system uses a Type field. This field plays a key role when an object undergoing changes has a primary type that divides all such objects into smaller groups. The value of this Type field is passed in the Webhook notification.

For example, in the case of a transaction, the 'Transaction' object contains a Type field that categorizes all transactions, such as 'Invoice', 'Payment', etc. Thus, in notifications related to 'Transaction', in addition to Id, Type will also be indicated. This allows the integrator to handle only those notifications that are associated with objects of a certain type.

It's important to note that the Type field is added when an object contains an Enum that divides all objects of this type into smaller groups. This is especially useful when there is a high probability that the processing logic will be specific to each group. For example, in notifications related to 'Transaction', Type is passed, allowing the integrator to handle notifications related to a certain type of transaction, ignoring all others.