Webhooks

Overview

In response to some events, we generate and send out a webhook message to your defined URL.

All ClearBank webhooks consist of a DigitalSignature, Type,Version,Payload and Nonce. Payload parameters vary depending on the webhook. Webhook responses contain a 200 HTTP status code which includes a Nonce number in the body and your DigitalSignature.

Anatomy of a webhook

ElementTypeDescription
DigitalSignaturestringClearBank®'s Digital Signature
TypestringThe type of the event
VersionintThe webhook version
NonceintCryptographically secure number generated by ClearBank® for every single webhook. A nonce number is generated randomly and should not be used as a check for duplication
Payloadarray[object]Object which contains information related to the webhook

Response

ElementTypeDescription
DigitalSignaturestringSigned hash of the body of the request. The hash signed by your private key
200 arrayHTTP response status code

Responding to a webhook

The webhook sent by ClearBank® acts as a verification mechanism. You verify that it is ClearBank® that has sent you the webhook and subsequently, ClearBank® needs to verify that you have successfully received the webhook (based on your response acknowledging receipt). This verification occurs when you return a 200 HTTP response, which includes the Nonce number in the response body and your DigitalSignature. If your response is invalid, we will consider it as a failed webhook. ClearBank® will send the webhook every 15 minutes for 24 hours unless a successful response is returned by you.

To create the webhook digital signature:

  • Take the Nonce number from the webhook and place it in the body of the response (e.g. "{"nonce": <value>}"
  • Hash the response body using SHA 256
  • Sign the hash with your Private Key and attach the signed hash as Base64 encoded in the DigitalSignature Response Header

Your Private Key needs to correspond to a Public Key which has been used to create a Certificate Signing Request (CSR). Please refer to creating your authentication profile for more information.

Example webhook request body:

{
"Type": "FITestEvent",
"Version": 1,
"Payload": {
"Hello": "World"
},
"Nonce": 1448545215
}

Example 200 Response

DigitalSignature string, Header,REQUIRED

This is a hash of the request body, signed with your private key.

{
"Nonce": 1448545215
}

Setting up and testing webhook listener URLs

You can create one webhook listener for all events or separate webhook listeners specific to an event. In this example, you will setup an FITestEvent webhook URL, which you can test against the TEST POST endpoint.

To manage your webhook definitions and set your webhook listener URLs for each event:

  • Log in to the Institution Portal. More information about accessing the portal can be found here
  • From the menu, select Institution > Webhook Management.alt text
  • Scroll down to FITestEvent webhook and Click the Set URL button
  • Enter the URL you want to define as your webhook listener for this webhook.
  • Click Submit to successfully setup the webhook listern URL. This will automatically enable it
  • To test the webhook, click the *Send test button
  • Enter a test message in the Test webhook window for example, ‘Hello World’ and click Send

You should receive a FITestEvent webhook to your nominated URL and it should contain the test message in the body.

The range of public IP addresses to support your interaction with the ClearBank® API and webhooks are:

  • Simulation Public IP address range: 51.145.122.16/28
  • Production Public IP address range: 51.145.122.32/28

Downloading Your Public Key

You can download a Public Key that is specific to your institution from the Institution portal. This Public Key must be used to verify the integrity of the webhook received from ClearBank®.

To download your Institution’s Public Key:

  • Click the Download Public Key button on the Webhook Management page.
  • Save the Public Key as a .pem

Accounts

Virtual Accounts

Payments

You may occasionally receive multiple webhooks with the same EndtoEndTransactionId. In this instance, a duplicate check should take place using the TransactionId. If the same TransactionId is used for both payments, the webhook will be a duplicate. In case the TransactionId(s) are different, these will relate to separate transactions.

A full list of webhook documentation is available on ClearBank®'s Knowledge Centre and access can be granted as part of your onboarding journey. Please reach out to your main contact ClearBank® for more information.