Webhooks

A webhook enables you to obtain automatic transaction updates, or for notifications where the response is delayed.

It allows you to send real-time data from one application to another whenever a given event occurs.

Use cases

You can use webhook event notifications to alert you:

• That an invoice has been created( invoiceCreated ) - Optional
• That an invoice has been completed ( invoiceCompleted ) - Required
• That an invoice has been canceled ( invoiceCancelled ) - Optional

Steps to receive webhooks

Use the webhooks attribute and provide:

1. URL (This is usually transaction specific)
2. webhook event: one of the above listed events
3. method: POST/GET/PUT/DELETE

Request example

"webhooks":[

{

"method": "get",

"url": "https://0a9c7748486fec.m.pipedream.net/transactions/updates",

"event": "invoiceCompleted"

},

{

"method": "get",

"url": "https://0a9c77481236fec.m.pipedream.net/transactions/updates",

"event": "invoiceCancelled"

}

]

Webhook signature (optional)

To enhance the webhook security further, we support signing the payload with SHA-256 hmac signature for each of the POST webhook we sent. This will allow your server to ensure it's only receiving requests coming from Tyro Health Online.

Setup

To set up the webhook signing, please contact the customer support to apply for a secret token that will be used for signature signing. Once the secret key is generated, it will be delivered either via keybase (preferred) or secure email.

Validating request from Tyro Health Online

Once your secret token is set by Tyro Health Online, every POST requests coming from Tyro Health Online will include two additional headers:

- X-Sender-Signature | A SHA-256 HMAC hash that's generated based on X-Sender-Timestamp value and JSON stringified payload.
- X-Sender-Timestamp | Date in ISO date string format. It represents the date the request was sent. Also, It will be used for HMAC hash calculation.

| ...
 X-Sender-Signature=215d022a9e9c95fab7ca7c618d0d7b8d9e6dca1055d544b3d2421312a16a5651
 X-Sender-Timestamp="2021-01-13T04:23:50.659Z" 

To verify the hmac signature, you will need to compute your own SHA-256 HMAC signature and compare it with the signature provided in the header. So the code will be something like this:

const hmacSignature = Crypto.createHmac("sha256", SECRET\_TOKEN)
 .update(`${headers["X-Sender-Timestamp"]}${JSON.stringify(payload)}`)
 .digest("hex");
return Crypto.timingSafeEqual(new Buffer.from(hmacSignature, "utf-8"), new Buffer.from(headers["X-Sender-Signature"], "utf-8")); 

Implementation between different languages might be different. However, things to note above are:

• The HMAC function has to use SHA256 method
• The base for computing the hash is consisted of the timestamp in the header and stringified payload in the request
• Try to use timingSafeEqual equivalent function to compare the HMAC result to avoid timing attack on large string comparison