You are here: Resources > Webhooks > Webhooks Configuration

Webhooks Configuration

To set up Webhooks you will need to:

  1. Create an endpoint.
  2. Configure the Webhook(s) you require.
  3. Listen for events.

Creating an Endpoint

Before you can use Nuapay Webhooks you must set up a dedicated Endpoint on your Web server. The steps required to configure your endpoint will vary depending on the Web server that you are currently using.

Setting up a Webhook

To set up a Webhook:

  1. Log on to the Developer Dashboard (currently available from the Origix Corporate home page).
  2. Click Add Webhook.
  3. Add the required details in the pop-up dialog box:
  4. Specify:
    1. The name of the Webhook notification.
    2. The URL of the Endpoint you configured.
    3. Status is set to Enabled by default (if Disabled no notifications are generated).
    4. Retry period (determines for how many days failed notifications will be retried. Retries are automatically generated every 30 minutes).
    5. Sign Key is the secret key that the application uses to sign the notification JSON body. The signature is sent in the request HTTP 'X-Signature' header. If you leave this field blank the application will automatically generate a key.
    6. The Event Types drop-down allows you to configure what events will trigger the notification to the Webhooks Endpoint URL. In the example above only Refunds will trigger a notification but you may define 1-n events as required.
  5. Click Submit.

X-Signature

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 (you configured in step 4 (e) above) 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 on your Nuapay account 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:

  • IncomingCreditTransfer
  • DirectDebitAccept
  • DirectDebitCancel
  • DirectDebitRefuse
  • DirectDebitReject
  • DirectDebitReturn
  • DirectDebitRefund
  • MandateElectronicSign
  • MandatePaperActivation
  • MandateCreation
  • CreditTransferReject
  • CreditTransferCancel
resourceReference String Max 255 chars This is the reference to a specific resource (Direct Debit, Credit Transfer) . 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 i.e. the End-To-End ID.
resourceUri String Max 255 chars

This is the URI to the resource being referenced in the event. For an event related to an R-transaction, for example, you can use Retrieve Direct Debit with this URI reference to retrieve the Direct Debit Direct Debit resource.

For an Incoming Credit Transfer, use the provided accountId and transactionId to retrieve details of the transaction (for more on this see the Transactions resource in the API Reference section)

resourceType String Max 255 chars The type of the resource to which the resourceUri is related. Direct-Debit-related events have a type 'DirectDebit'; Incoming-Credit-Transfer-related events have a type 'Transaction'.
reasonCode String Max 6 chars This is only available for the R-Transaction type of events and includes the SEPA Error Code.

Sample Webhook Notifications

The following is an example of a Direct Debit Reject event JSON:

        
POST http://example.com/webhooks
Content-Type: application/json;charset=UTF-8
X-Signature: 521ab01d030dee864fb44cc65a3be52ae591f46cde8d14d3e72fbc3790e4a304
Content-Length: 261
X-Request-Id: dc645679-71a5-498d-bb29-ec027948c7c1
	{
		"eventTimestamp": 1501169079000,
		"eventType": "DirectDebitReject",
		"resourceReference": "Webhook1",
		"resourceReferenceType": "EndToEndId",
		"resourceUri": "/schemes/p2lqa394mv/mandates/lbyjxj5ebd/directdebits/a2rexnvdmq",
		"resourceType": "DirectDebit",
		"reasonCode": "MS03"
	}
		

Use the resourceUri to retrieve additional details related to the event; see Retrieve Direct Debit.

The JSON for an Incoming Credit Transfer Event would be similar to the following sample:

 
		
POST http://example.com/webhooks
Content-Type: application/json;charset=UTF-8
X-Signature: 521ab01d030dee864fb44cc65a3be52ae591f46cde8d14d3e72fbc3790e4a304
Content-Length: 261
X-Request-Id: dc645679-71a5-498d-bb29-ec027948c7c1
	{
		"eventTimestamp": 1500651159000,
		"eventType": "IncomingCreditTransfer",
		"resourceReference": "DemoE2EID",
		"resourceReferenceType": "EndToEndId",
		"resourceUri": "/accounts/qj29pkgnbx/transactions/ym37ygrg23",
		"resourceType": "Transaction",
		"reasonCode": null
	}