Webhooks

POST {{messageUrl}}

Encryption

BGL will compute a Hash-based(SHA256) message authentication code (HMAC) using a secret key to protect the integrity and the authenticity of the message. The following logic will be used to generate a token which sends as an authorization header which can be decoded from provider's end with the same private key

Authorization : "{clientCode} {UTC Date String} {Signature}"

       client code = this is code in lowercase unique for the client
       UTC Date String = timestamp in UTC format yyyy-MM-dd'T'HH:mm:ss.sssZ
       Signature = This will contain following data which will generate HMAC using SHA256 hash, using configured secret. 
                           "{UTC Date String}POST{URI String}{RequestBody}"

      Calculating Signature,

      Signature = Base64Encoded(HMAC("{UTC Date String}POST{URI String}{RequestBody}"))

Example

provider code: "provider1"

time stamp string (utcStr): "2020-09-09T06:18:33.082Z"

the request url (urlStr): "https://provider-site.com/api/bgl/messages"

secret key (secret): "my-secrete-key"

requestBody: '{"entityId":"8ad08a066555bb32016555d9ebac0003","eventId":"039403940","eventType":"audit","firmId":"bgltest","tenants":[{"tenantId":"ASFAUDIT4550","tenantType":"fundCode"},{"tenantId":"73124784265","tenantType":"abn"},{"tenantId":"2015/2016","tenantType":"financialYear"}],"userId":"info@bglcorp.com.au"}'

To generate the signature:

1. get the string to sign: utcStr + "POST" + urlStr + requestBody
based on the value above, the string should be:
2020-09-09T06:18:33.082ZPOSThttps://provider-site.com/api/bgl/messages{"entityId":"8ad08a066555bb32016555d9ebac0003","eventId":"039403940","eventType":"audit","firmId":"bgltest","tenants":[{"tenantId":"ASFAUDIT4550","tenantType":"fundCode"},{"tenantId":"73124784265","tenantType":"abn"},{"tenantId":"2015/2016","tenantType":"financialYear"}],"userId":"info@bglcorp.com.au"}

2. use sha256 to generate the signature, sample codes:
    Mac mac = Mac.getInstance("HmacSHA256")
    mac.init(new SecretKeySpec(secretKey.getBytes("UTF-8"), mac.getAlgorithm()))

    byte[] digest = mac.doFinal(stringToSign.getBytes())

    return digest.encodeBase64().toString()

3. The final sigature generated:
fcCSdGwSgTXseS5eFWOphImuEM9LT6KjgHfuiPWB48A=

4. The Authorization header value:
provider1 2020-09-09T06:18:33.082Z fcCSdGwSgTXseS5eFWOphImuEM9LT6KjgHfuiPWB48A=

### Request Body

The same format will be sent for all message types.

tenants array

### Responses

Outlined below and in the examples are what BGL expects for webhook responses.

• Success

  • response code: 200
  • response type: application/json
  • response body { message: "request accepted." } { message: "request accepted.", resourceUrl: "https://www.google.com/" }

• Validation Error

  • response code: 400
  • response type: application/json
  • response body { message: "missing required parameters", errors: [ "fundId is missing", "financialYear is missing" ] }

• Other Runtime Errors

  • response code: 500
  • response type: application/json
  • response body { message: "System maintenance." }

HEADERS

RESPONSES

status: OK

"{\n  message: \"request accepted.\"\n}"