Webhook notifications are passed to your configured Endpoint; this section gives you some important security and configuration information to consider when setting up your receiving endpoint.


To ensure that you can be confident that the Webhook message received by your defined Endpoint has actually been dispatched from Nuapay, we encode the Sign Key (as configured on the Add Webhook pop-up via the Developer Dashboard screen or via the signKey value in the Create Webhook API) using HMAC: Keyed-Hashing for Message Authentication .

Before transmitting the Webhook message to your Endpoint, Nuapay creates a hash value based on your Sign Key. Nuapay uses the Apache Commons HmacUtils codec for the encoding; the hashed value is then passed in the X-Signature.

import org.apache.commons.codec.digest.HmacUtils;
String xSignature = HmacUtils.hmacSha256Hex(signKey.getBytes(), body);

For more information on HMAC see https://tools.ietf.org/html/rfc2104

Listening for Events

When an event occurs it is notified to your configured endpoint URL.

Notification Details - HTTP POST Request

Method POST
Content-Type application/json

Extra Request Headers

Header Name Header Value
X-Request-Id UUID of the Webhook Notification
X-Signature Signature of the request JSON body, created with the Sign Key stored on the Webhook

Request Body

JSON Path Type Description
eventTimestamp Number Max 19 chars The Epoch timestamp format of the date and time that the event was triggered
eventType String Max 255 chars

The type of event to which this notification is related. The event can be one of the following, for example:

  • PaymentRecieved
  • PaymentReversed
resourceReference String Max 255 chars This is the reference to a specific resource (received or reversed payment). The type of reference is specified by the resourceReferenceType.
resourceReferenceType String Max 255 chars This is the resource reference type to which the resourceReference is related.
resourceUri String Max 255 chars

This is the URI to the resource being referenced in the event. You can use Retrieve Payment to retrieve the payment details.

resourceType String Max 255 chars The type of the resource to which the resourceUri is related; a payment resource in this scenario.
reasonCode String Max 6 chars Null.

For details of the Webhook Event messages and JSON samples, see the events descriptions provided under your required Product (i.e. Nuapay, Open Banking, etc.)

Webhook-Triggering IPs

Nuapay Webhooks are triggered from the following IP addresses: