Notifications

Hyperwallet servers communicate entity and status changes to the connector using webhooks. A webhook is a notification that is received by the connector in the '/webhook/notifications' endpoint.

Storing and filtering

Hyperwallet API doesn’t guarantee that the notifications are sent in the same order as the events that generated them. This could cause issues like changing the KYC status of sellers that were already verified.

To avoid such issues, and following Hyperwallet recommendations, the connector stores the notifications received, and filters out the obsolete and duplicated ones.

Behaviour

When then connector receives a notification it stores it in a database, except for two different cases:

  • Duplicated notification: the same notification already received and stored in the database

  • Obsolete notification: a notification for the same item (a specific seller, stakeholder…​), but created before the existing one already stored in the database.

Diagram Description automatically generated

The connector stores the following information in the NotificationEntity table:

Database field Data type Notes

id

Long

Autogenerated ID

webhookToken

String

Token of the notification

objectToken

String

Token of the related item

creationDate

Date

Creation date of the notification by Hyperwallet

receptionDate

Date

Date of reception of the notification in the connector

notificationType

String

Type of the notification, containing one of the following possible values: USR, PMT, STK, TRM, UNK

The connector extracts the notification type from the three first characters of its token. The possible values are:

  • USR: Sellers

  • STK: Stakeholders

  • PMT: Payments (invoices)

  • TRM: Bank account

  • UNK: Unknown

Hyperwallet never sends an unknown type notification, however, if the connector can’t parse the notification token, then it stores an UNK value for the type to avoid a failure.

Querying and housekeeping

Two different endpoints are available to query or to remove the notifications stored in the database.

Endpoint Method Description

/webhooks/notifications

GET

Query the notifications stored in the database

/webhooks/notifications

DELETE

Remove the notifications stored in the database

The endpoints receives two parameters (from and to) query or remove the notifications received within such period. The connector doesn’t offer a job to remove the notifications automatically, and the user is responsible on triggering (manually or automatically).

Example of valid execution request for both querying and removing notifications:

curl --location --request GET 'http://localhost:8080/webhooks/notifications?from=2021-04-27T10:30:00.000-00:00&to=2023-04-27T10:30:00.000-00:00'

curl --location --request DELETE 'http://localhost:8080/webhooks/notifications?from=2021-04-27T10:30:00.000-00:00&to=2023-04-27T10:30:00.000-00:00'

Retry mechanism

The connector retries the processing of the notifications received from Hyperwallet in case it’s impossible to upload the information in Mirakl.

Functionality behaviour

The connector uses an internal database to support the retry functionality without storing sensitive information. A periodical job retrieve such notifications from Hyperwallet and then tries to update Mirakl again until they reach the maximum number of attempts allowed.

When a failed notification is stored in the database and a new one is received, the connector checks the following cases:

  • Identical existing notification, the connector skips the notification, as it’s identical to the previous one.

  • Updated existing notification, the connector receives a notification for the same item (e.g., a user) with a creation date later than the one stored. In this cases the connector processes the received notification and drops the old one.

  • Outdated existing notification, the connector receives a notification for the same item (e.g., a user) with a creation date before the stored one. In this cases the connector ignores the received notification.

When all retry attempts for a notification are exhausted, the connector removes it from the database and sends an email to the operator.

Configuration

The connector reads the configuration from the following configuration variables:

  • PAYPAL_HYPERWALLET_RETRY_NOTIFICATIONS, set to true to enable retries, or false to deactivate them. Set to true by default.

  • PAYPAL_HYPERWALLET_MAX_AMOUNT_OF_NOTIFICATION_RETRIES, determines the maximum number of attempts allowed for each notification. Set to 5 by default

  • PAYPAL_HYPERWALLET_RETRY_FAILED_NOTIFICATIONS_CRON_EXPRESSION, used to configure the periodicity of the retry job. === Email alerts

The connector sends an email to the operator when all the retries of a notification fails. The email includes the following details:

Subject: [HMC] Technical error occurred when processing the notification <NOTIFICATION_TOKEN>

Body: There was an error processing the notification <NOTIFICATION_TOKEN> and the operation could not be completed. The maximum number of attempts <NOTIFICATION_TOKEN> has been reached, therefore it will not try to re-process the notification anymore. Please check the logs for further information.