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


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 the notification is related.

resourceReference String Max 255 chars This is the reference to a specific resource e.g. an End-to-End Identifier for a Direct Debit transaction. 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.

resourceType String Max 255 chars The type of the resource to which the resourceUri is related.
reasonCode String Max 6 chars The reason code, where applicable (e.g. where the Webhook relates to a rejected Direct Debit payment).
resourceOwner String Max 255 chars This is the identifier of the merchant resource to which the notification is linked.
resourceRemittanceInformation String Max 140 chars Remittance Information specific to the transaction.

For details of the Webhook Event messages and JSON samples, see the events descriptions provided under your required Product (i.e. Direct Debits & Credit Transfers, Electronic Mandates, Open Banking, etc.)

Webhook-Triggering IPs

Nuapay Webhooks are triggered from the following IP addresses: