# 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


```js
"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:


```js
- 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:


```js
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