What is a Webhook?
Imagine that you're waiting for an important package to arrive at your doorstep. Instead of constantly checking your front door, you set up a notification system. This system will send you a message every time the delivery person arrives and drops off the package. That way, you can go about your day and be notified exactly when the package arrives, without constantly checking for it.
In the world of web development, Webhooks work in a similar way. They are a way for one application to notify another application automatically when something specific happens. It's like setting up a virtual "doorbell" for important events.
Our Webhooks API allows you to subscribe to events happening. Rather than making an API call when an event happens, NikoHealth can send an HTTP request to an endpoint you configure.
Here's how it works:
An application (let's call if Client App) wants to be notified when a particular event occurs.
Client App provides a URL (web address) to NikoHealth that it wants notification to be sent.
Whenever the specified event occurs in NikoHealth, it sends a data payload ( a message) to the URL provided by the Client App.
Client App receives the payload and can then take some action based on the information received.
Webhooks allow applications to communicate with each other in a real-time manner. Instead of constantly asking, "Has the event happened yet?" like repeatedly checking your front door, Client App sets up a Webhook to receive automatic notifications when the event occurs in the NikoHealth platform.
Webhooks are commonly used in various scenarios, such as receiving notifications about when a resource such as a patient or order is created or updated, with the intent to sync data between different systems.
What Webhooks are supported by NikoHealth?
To get the list of supported webhook notifications you can use the:
HTTP GET to /v1/webhook-event-types within the Swagger documentation provided.
How to work with NikoHealth Webhooks?
Subscribe to a Webhook
You can use the Swagger portal provided to you to play around with creating a webhook.
Type "Web" in the input field where you see Filter by tag hint
In the filtered list of Web Hooks group of records - expand by clicking the one that starts with the POST /v1/webhooks
Click the Try it out button located on the right side of the expanded area
In the Request body text area which became enabled add your request payload as in the sample below:
{
"Events": [
"patient.created"
],
"Url": "https://webhook.site/9bf81526-00c9-47ef-9558-d9acb11d11ef",
"Status": "Active"
}
5. Click the blue Execute button right below the Request body text area
6. Await for the request being executed with the result shown right below the Execute button, under the Responses section
7. From the Response Body you will need Secret value to verify that Webhook received was sent by NikoHealth.
Communication protocol with webhooks
A webhook is sent whenever an event that you have subscribed to occurs on the NikoHealth platform.
A webhook is sent using an HTTP POST to the URL that was registered when the webhook was created, with a body encoded in JSON.
NikoHealth expects the server that responds to a webhook will return a 2xx response code. If a non-2xx response is received or NikoHealth does not receive a response to the webhook within this period, NikoHealth will assume the delivery has failed. NikoHealth will retry up to an additional 5 times. The timeout period is 5 seconds increased exponentially with each attempt.
Webhook headers
A number of HTTP headers are set on webhooks, as detailed in the table below.
Header Name | Value |
| application/json; charset=utf-8 |
| A signature could be used to verify that NikoHealth is the sender of the webhook. This consists of:
|
Validate Webhooks
You should validate incoming webhooks to verify that they are coming from NikoHealth. To support this, when creating a webhook you are provided with a secret token. Each outgoing HTTP request to your service will contain a signature header.
What is HMAC Signature?
Imagine you want to send a secret message to your friend, but you also want to ensure that the message hasn't been tampered with during transmission. You decide to add a special code to the message that will act as a seal.
You take the message and apply a secret formula to it, which generates a unique code. This code is called the HMAC signature. You then send the message along with the HMAC signature to your friend.
When your friend receives the message, they can use the same secret formula to independently generate the HMAC signature. If the calculated signature matches the one you sent, it means the message hasn't been altered during transmission and can be trusted.
In simpler terms, the HMAC signature is like a digital seal that ensures the integrity and authenticity of a message. It helps verify that the message hasn't been modified or tampered with by someone unauthorized.
How to validate the HMAC Signature?
HMAC keys consist of two parts. These are:
Cryptographic keys : This secret key is a small set of data that helps authenticate the nature of the message. This will be used as a unique piece of information to compute the HMAC and is known between the sender (NikoHealth) and the receiver(Client App) of the message.
Hash Function. A hash algorithm that digests the message using a digital algorithm such as SHA256 hash function.
HMAC tester tools can help demonstrate how something like this works.
Step 1. Extract the timestamp and signatures from the header
Split the header, using the , character as the separator, to get a list of elements. Then split each element, using the = character as the separator, to get a prefix and value pair. The value for the prefix ts corresponds to the timestamp, and sign corresponds to the signature. You can discard all other elements
Step 2. Prepare the signed_payload string
You achieve this by concatenating:
· The timestamp (as a string)
· The character .
· The actual JSON payload (i.e., the request’s body)
Step 3: Determine the expected signature
Compute an HMAC with the SHA256 hash function. Use the endpoint’s signing secret as the key (this is the secret token provided when subscribing to the webhook), and use the signed_payload string as the message.
Step 4: Compare Signatures
Compare the signature in the header to the expected signature. If a signature matches, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance.