Invoice Notifications

How are Invoice Notifications sent via Webhook?

What are Webhooks?

Webhooks allow you to connect to quickclaim mercury, a digital invoicing network for NDIS transactions. By subscribing your webhook URL to the available mercury event categories you can integrate your billing system with quickclaim to automatically receive invoice documents that are issued for you.
When one of these events are triggered, quickclaim makes a POST call to your Webhook’s endpoint and sends the details of the invoice in the payload of the call.

Webhook Security

Webhook security refers to the measures and practices implemented to ensure the integrity, authenticity, and confidentiality of data exchanged between quickclaim and your system through webhooks. A webhook is a way for one system to send real-time data to another system as soon as a specific event occurs. These events can trigger actions or updates in the receiving system.

Ensuring webhook security is crucial to prevent unauthorised access, data breaches, and other malicious activities. Here are some key aspects of the webhook security that quickclaim follows:

Encrypted data sent through webhooks

While we can’t prevent bad actors from intercepting our messages, we can prevent them from reading the contents. A simple way to ensure that all communication happens securely is using HTTPS instead of HTTP. Your Webhook URL must support and use https protocol with a valid certificate.

Added timestamps to your message

Quickclaim tags messages with a timestamp to help prevent replay attacks. Replay attacks don’t read or manipulate messages, but they can catch a legitimate, encrypted message and resend it at an opportune moment.

By tagging our messages with timestamps, we enable the client to ensure that the message sent is current and not something we sent out a couple of weeks ago. Since our messages are also signed, the attacker can’t change the timestamp or save the message for a replay attack.

Signed payloads in webhooks

Bad actors can intercept messages sent on the internet and change their contents to benefit themselves. To prevent unwanted changes, we sign our messages before sending them to your endpoint. The sign and verification key pair are issued and saved in Quickclaim after completing Webhook URL setup and the verification key (public key) will be available for you to download. Quickclaim signs all webhook events sent to your endpoints with a signature. This signature appears in each event's X-Quickclaim-Request-Signature header. The message input for generating signature appears in each event's X-Quickclaim-Signed-Input header. This allows you to verify the integrity of the data and the provider's authenticity from which data is coming.

Whenever a webhook is triggered for a specific event, Quickclaim generates a signature based on the a selected set of header values and appends it to the X-Quickclaim-Request-Signature header of the HTTP request. The message input is created as the hash value of the following headers:

• X-Quickclaim-Event-Resource-ID

• X-Quickclaim-Request-Timestamp

The values taken from above mentioned headers are joined using semicolon ; and then passed to the hash function to generate based64 encoded hash from the source string.

X-Quickclaim-Request-Signature: BQIMHh4VbuCM5tx9OL2ee1k40sXu99tLXIQ88AJ5esSwd45L/b9yYifQ9pA9+/hZidUWnDxsR2FnP1uMPuQN+waq99Upy+AEtjDpb67Z+sbEVgneY+PC1W/WuqKQ6kouAbvjksxZnNNAa95P6u8/IEy+SvNI/Sg5v7td2lcPcTgQRMgNEbWjhgOQNpuG4oievICEhQgQa8cpadEXPp4Hda1E0qvLBhoUX5YqWJNxh464K8KKOW5zwp7d8WCMEakM13nsSYsu5gezZK8btBOEMmM3xcSvpQEnY119P4LJOgZzBDT3QHa26M3cCElh0ID4XXv/kemPWZ3aX5OV5XSHzw==

Steps to verify the signature

1. Load/ Read your Public key and keep it in the memory

2. Read the Attached Signature value from header key: X-Quickclaim-Request-Signature

3. Read the Attached message hash value from header key: X-Quickclaim-Signed-Input

4. Use the public key in combination with message input to verify the signed value

5. If signature is valid, take the timestamp and verify whether it is for today

   
   const crypto = require('crypto');
   const fs = require("fs");
   
   // ...
   
   // Load public key
   publicKey = fs.readFileSync("quickclaim_generated_public_key.pem", "utf8");
   // read the body text
   const input = request.headers["X-Quickclaim-Signed-Input"]
   // read the signature
   const sign = request.headers["X-Quickclaim-Request-Signature"]
   // create verifier
   const verifier = crypto.createVerify("RSA-SHA512");
   // add the payload
   verifier.update(input);
   
   const isValidSignature = verifier.verify(publicKey, sign, "base64");
   const timestamp = request.headers["X-Quickclaim-Request-Timestamp"];
   const isTimestampForToday(timestamp);
   
   return isValidSignature && isTimestampForToday;

    

If you could successfully run and pass the assertions against request’s metadata (e.g. sign, timestamp) you can trust the content (payload) of the call and process the included documents in your system.

Events

When you configure a webhook URL the following categories of events will be sent to your endpoint. Within each category there are certain types of events that can happen (e.g. create, update)

Each event contains shared properties, but has a unique payload object determined by its event Event Category as well as Event Type. The common properties describes the properties shared by all events, and each event category & type describe the payload properties that are unique to the specific event.

Event object common properties

{
  "documentId": "hdow5nd7XAnhH9C66QqMn",
  "category": "Invoice"
  "type": "CREATE",
  "resourceUrl": "https://api.quickclaim.io/mercury/invoices/c402ee45-dbc3-4da3-8318-c9cd3f03207b",
  "resourceId": "c402ee45-dbc3-4da3-8318-c9cd3f03207b",
  "eventDispatchDate": "2023-01-01T12:10:20.000Z"
  "tenantId": "34567",
  "tenantType": "Provider",
  "payload": {...}
}

Event Category and Type Payload

Invoice - CREATE

This event is sent to your webhook whenever a new invoice in Quickclaim has been issued to you.

Event payload object

Invoice Data object model

Invoice Contact object model

Invoice Header object model

Invoice LineItem object model

Invoice Payment object model

Invoice Metadata object model

Invoice Email object model

 

 

{
    "documentId": "hdow5nd7XAnhH9C66QqMn",
    "category": "Invoice",
    "type": "CREATE",
    "resourceUrl": "https://api.quickclaim.io/mercury/invoices/c402ee45-dbc3-4da3-8318-c9cd3f03207b",
    "resourceId": "c402ee45-dbc3-4da3-8318-c9cd3f03207b",
    "eventDispatchDate": "2023-01-01T12:10:20.000Z",
    "tenantId": "34567",
    "tenantType": "Provider",
    "payload": {
        "data": {
            "from": {
                "companyName": "quickclaim",
                "legalName": "quickclaim pty ltd",
                "abn": 12345678910,
                "address": "100 Harris Street, Pyrmont NSW 2009",
                "website": "www.quickclaim.io",
                "phone": "1300 311 780",
                "email": "amir@quickclaim.io",
                "contactPerson": "Amir Hosseini"
            },
            "to": {
                "companyName": "quickclaim",
                "legalName": "quickclaim pty ltd",
                "abn": 12345678910,
                "address": "100 Harris Street, Pyrmont NSW 2009",
                "website": "www.quickclaim.io",
                "phone": "1300 311 780",
                "email": "amir@quickclaim.io",
                "contactPerson": "Amir Hosseini"
            },
            "header": {
                "invoiceId": "1234",
                "invoiceNumber": "INV-29082023-000123",
                "reference": "23894701837408123740",
                "issueDate": "2023-05-14",
                "dueDate": "2023-06-14",
                "totalAmountExcludingGst": 1100,
                "totalGstAmount": 120.34,
                "totalAmountIncludingGst": 1200.34,
                "participantFullName": "Jack Nicholson",
                "ndisNumber": 437689896
            },
            "lineItems": [
                {
                    "lineId": "LI3453453",
                    "description": "Line Item Description",
                    "supportItem": "01_011_0107_1_1_T",
                    "unit": 500,
                    "rate": 2.5,
                    "amountExcludingGst": 1250,
                    "amountIncludingGst": 0,
                    "gstAmount": 0,
                    "serviceStartDate": "2020-07-14T08:30:00.000",
                    "serviceEndDate": "2020-07-14T10:30:00.000"
                }
            ],
            "payment": {
                "payTo": "quickclaim",
                "bank": "quickclaim pty ltd",
                "bsb": 111222,
                "accountNumber": "12345678910",
                "website": "www.quickclaim.io",
                "phone": "1300 311 780",
                "contactPerson": "Amir Hosseini",
                "remittanceAdviceEmail": ""
            }
        },
        "metadata":{
            "invoiceDocumentUrl": "https://presigned-dynamic-url-to-invoice.com/xyz234234/....",
            "createdAt": "2020-07-14T10:30:00.000",
            "updatedBy": "2020-07-14T10:30:00.000",
            "updatedAt": "User123"
        },
        "email":{
            "emailId" : "1241ee45-dbc3-4da3-8318-c9cd3f052525", 
            "subject" : "INV-123",
            "from" : "abi@pm.com.au", 
            "body" : "Hi There, ......" 
        }
    }
}