Webhooks & event handling

In order to subscribe to NHP events, you need to do similar JWT signed request to Subhub that you do with NH Pay API. JWT contains the target tenant ern for the tenant events you want to subscribe to. You subscribe to list of events, and provide a webhook address which is capable of receiving the notifications.

Setting up webhoooks

Subhub uses a shared secret HMAC to verify the POST request authenticity. When subscribing, you provide the shared secret to subhub. In the header of the request from Subhub to your webhook url, you should always receive ‘Subhub-Hmac’ value, which you should compare by creating a hmac object from the body of the request with your secret key, and then comparing the genereated hmac object to the one received in the request header.

The actual subscription happens by calling the subhub with following path (GET, PUT, DELETE):

/my/subscriptions/<subscription_id>

Example request body

{
  'publisher': 'https://pay.etrust.health',
  'events': [
    "payment_link.created",
    "payment_link.expired",
    "payment_link.completed",
  ],
  'destination': <Your publicly available incoming webhooks URL>,
  'protocol': 'http',
  'signing_key': <SUBHUB_SIGNING_KEY>
}

You can define your own subscription_id e.g. for different types of events, or you can just target all neede events with single id. Signing key is the shared secret used with HMAC.

See main.py on subscribing / unsubsribing to events with Subhub.

Transaction notification handling in PMS

In typical integrations all notifications are sent “as duplicates” using the two available delivery channels (JS callback and Subhub webhook). Proper handling of the race condition in the PMS is critical. The following diagram shows the recommended notification handling logic for PMSes to implement to avoid race conditions.

The notification header.event_id will be same when the same notification is sent using multiple channels. An atomic counter (e.g. in Redis) for the event_id could also be used to avoid duplicate event processing.