Webhooks

Webhooks are used to receive events from Commbank relating to PayTo Agreements and Payment Initiations. To receive webhooks you must create a Callback API Endpoint so that we can deliver these events to you.

Events Overview

Events are generated to notify you of asynchronous activities performed on your payments and PayTo Agreements.

PayTo Agreement Events

PayTo Agreement Event Sample

{
  "id": "2a38567a-c7d4-4dd9-a5cd-e658565940ae",
  "eventName": "AGREEMENT_ACTIVATED",
  "apiVersion": "1",
  "createdDate": "2024-06-18T04:20:19.324Z",
  "data": {
    "agreementID": "0ca4bdc1-2d2a-11ef-b22d-a6034fd58c6f",
    "status": "activated",
    "statusReasonCode": "AC02",
    "statusReason": "customer simulated response",
    "initiator": "DEBTOR"
  }
}

PayTo Agreement Event Fields

PayTo Agreement Event Names and Statuses

PayTo Agreement Payment Initiation Events

Payment Initiation Event Sample

{
  "id": "1c6fab4b-16d1-4b45-86ec-55e97942d506",
  "eventName": "PAYMENT_FAILED",
  "apiVersion": "1",
  "createdDate": "2024-06-18T04:10:46.417Z",
  "data": {
    "agreementID": "947034ff-2d28-11ef-b394-76613a8a3c20",
    "nppMandateId": "3f4cb5da0000000000000000e1d6a07d",
    "paymentId": "bc8b1cf0-2d28-11ef-ba83-0d09ed77cf23",
    "status": "failed",
    "amount": "100.00",
    "currency": "AUD",
    "initiator": "DEBTOR"
  }
}

Payment Initiation Event Fields

• id the ID in UUIDv4 format for the Agreement that this notification relates to
• eventName the name of the event (refer to below table)
• apiVersion the version of the API you are using (currently 1)
• createdDate: timestamp of the event notification
• agreementID the ID in UUIDv4 format for the Agreement that this notification relates to
• nppMandateId the ID of the PayTo Agreement as stored at NPP's MMS (Mandate Management Service)
• paymentId the ID in UUIDv4 format for the Payment Initiation Request that this notification relates to
• status the status (refer to below table)
• amount the amount of the payment to 2 decimal places
• currency always AUD
• initiator The party that initiated the event that triggered this notification to be sent.

Payment Initiation Event Names and Statuses

Status Reason Codes

PayTo Initiator Values

Create a Callback API Endpoint

Receiving Events

Prerequisites

Commbank will send events to you with the custom headers. You should ensure that your Callback API Endpoint is secured, authentication and data integrity are handled to allow POST to your Callback API Endpoint.

Validating an Event

Commbank will sign events using an HMAC SHA-256 signature. To ensure data integrity, you should validate all events you receive by comparing the hash signature in the request header x-hmac-signature with the HMAC hash value you generate. To do this, you may want to use a common library for HMAC signature creation.

POST${consumer_url}${timestamp}${notification_payload}

Request Headers

Integration Guide

Decrypting and Verifying HMAC Signature

HMAC Format

The data string format for generating the signature is: POST${consumer_url}${timestamp}${notification_payload}.

Receive the Webhook

1. Extract the x-hmac-signature header from the incoming request.
2. Extract the timestamp from the headers and payload from the request.

Generate Local HMAC

Use the same method to generate the HMAC signature locally using the received timestamp and payload.

Compare Signatures

Compare the received HMAC signature with the locally generated one using timingSafeEqual to prevent timing attacks.

Sample Code

const crypto = require('crypto')

async function verifyHmacSignature(headers, request, path) {
  const secretKey = 'hmac-secret' // Load this from a secure source like Secrets Managers
  const consumerUrl = `https://${headers['host']}${path}`
  const timestamp = headers['timestamp']
  const payload = request
  const localHash = crypto
    .createHmac('sha256', secretKey)
    .update(`POST${consumerUrl}${timestamp}${JSON.stringify(payload)}`)
    .digest('hex')
  const authorizationHeader = headers['x-hmac-signature']?.split(' ') || ''
  if (authorizationHeader.length !== 2) {
    throw new Error('Header authorization not valid')
  }
  const hashFromHeader = authorizationHeader[1]
  const hashMatch = crypto.timingSafeEqual(Buffer.from(hashFromHeader), Buffer.from(localHash))
  if (!hashMatch) {
    throw new Error('Invalid HMAC signature')
  }
  // Signature is valid, process the request
  console.log('HMAC Signature is valid')
}