Skip to main content

Webhooks API

Subscribe to events so NikoHealth notifies your system automatically when something changes.

Overview

Subscribe to events so NikoHealth notifies your system automatically when something changes.

What is a Webhook?

Imagine you’re waiting for an important package. Instead of checking your front door all day, you get a notification when it’s delivered.

Webhooks work the same way. Instead of repeatedly calling the API to ask “has anything changed?”, you give NikoHealth a URL. When the event you subscribed to happens, NikoHealth sends an HTTP request to that URL with the details.

How it works:

  1. Your application (the Client App) subscribes to one or more events and gives NikoHealth a URL.

  2. When a subscribed event happens in NikoHealth, NikoHealth sends a JSON payload to your URL.

  3. Your Client App verifies the request and acts on it, for example by syncing the new patient or order to your system.

Webhooks are commonly used to keep systems in sync, for example when a patient or order is created or updated.


Supported Events

GET /v1/webhook-event-types

Optional filter: name.

Area

Events

Patients

patient.created, patient.updated, patient.deleted, patient.status.updated, patient.tags.updated, patient.diagnosis.updated

Patient documents

patient.document.created, patient.document.updated, patient.document.deleted

Patient notes

patient.note.created, patient.note.updated, patient.note.deleted

Patient payments

patient.payment.created

Insurance

insurance.created, insurance.updated, insurance.deleted

Orders

order.created, order.updated, order.deleted, order.status.updated, order.tags.updated, order.item.updated

Order documents

order.document.created, order.document.deleted

Invoices

invoice.created, invoice.updated, invoice.deleted, invoice.status.updated, invoice.tags.updated

Payments

payment.created, payment.updated, payment.deleted

Purchase orders

purchase-order.created, purchase-order.updated, purchase-order.deleted, purchase-order.status.updated

Inventory products

management.inventory.product.created, management.inventory.product.updated, management.inventory.product.deleted

Referring providers

referring-provider.created, referring-provider.updated, referring-provider.deleted

Tasks

task.created, task.updated, task.deleted, task.note.created

Faxes

fax.received, fax.deleted

New events are added over time. Call GET /v1/webhook-event-types for the current list.


Subscribe to a Webhook

POST /v1/webhooks

Field

Required

Notes

Url

✅

Your HTTPS endpoint that receives notifications

Events

✅

One or more event IDs from GET /v1/webhook-event-types

Status

✅

Active or Inactive

{
"Url": "https://your-app.example.com/webhooks/nikohealth",
"Events": ["patient.created", "patient.updated", "order.created"],
"Status": "Active"
}

Response: 201 Created

{
"Id": "string",
"Secret": "string"
}

🔑 Save the Secret right away. It’s only returned when you create the webhook. Retrieving the webhook later won’t show it. You’ll use it to verify that incoming requests really come from NikoHealth.

💡 Testing: In your sandbox, you can point Url at a request inspector such as webhook.site to see payloads. Don’t use public inspector tools with production data.


In Swagger

  1. Type Web in the Filter by tag box.

  2. Under Web Hooks, expand POST /v1/webhooks.

  3. Click Try it out.

  4. Enter your request body.

  5. Click Execute.

  6. Copy the Secret from the response body.


Manage Webhooks

Endpoint

Purpose

GET /v1/webhooks

List your webhooks (filter by event)

GET /v1/webhooks/{id}

Get one webhook (doesn’t include the secret)

PUT /v1/webhooks/{id}

Update the Url, Events or Status (send all three)

DELETE /v1/webhooks/{id}

Delete a webhook

To pause notifications without deleting the webhook, update its Status to Inactive.


How Webhooks are Delivered

  • Each webhook is sent as an HTTP POST to your URL, with a JSON body.

  • Your server should return a 2xx status code quickly.

  • If NikoHealth gets a non-2xx response, or no response within 5 seconds, the delivery counts as failed. NikoHealth retries up to 5 more times, waiting longer between each attempt.

💡 Respond fast, process later. Return 200 as soon as you’ve verified the signature, then do any heavy processing in the background. That prevents timeouts and duplicate retries.

Headers

Header

Value

content-type

application/json; charset=utf-8

signature

ts=<unix timestamp>,sign=<signature>


Validate Webhooks

Every webhook includes a signature header that you can use to confirm the request came from NikoHealth and wasn’t changed in transit. The signature is an HMAC-SHA256 hash created with your webhook’s Secret.

What’s an HMAC signature? Think of it as a tamper-proof seal. NikoHealth runs the message through a formula using a secret that only you and NikoHealth know, and attaches the result. You run the same formula on what you received. If your result matches, the message is authentic and unchanged.

Step 1: Extract the timestamp and signature

Split the signature header on ,, then split each part on =. ts is the timestamp, and sign is the signature. Ignore any other parts.

Step 2: Build the signed payload

Join these three values:

  1. The timestamp, as a string

  2. A . character

  3. The raw request body, exactly as received

⚠️ Use the raw body bytes. Don’t parse and re-serialize the JSON first, or the signature won’t match.

Step 3: Compute the expected signature

Compute an HMAC-SHA256 of the signed payload, using your webhook Secret as the key.

Step 4: Compare

  • Compare your computed signature with sign using a constant-time comparison.

  • If they match, check that ts is recent, for example within 5 minutes of the current time, to protect against replayed requests.

  • If either check fails, reject the request with a 401.

Example (Node.js)

const crypto = require("crypto");

function isValidNikoWebhook(rawBody, signatureHeader, secret, toleranceSec = 300) {
const parts = Object.fromEntries(
signatureHeader.split(",").map(p => p.trim().split("="))
);
const ts = parts.ts;
const sign = parts.sign;
if (!ts || !sign) return false;

const expected = crypto
.createHmac("sha256", secret)
.update(`${ts}.${rawBody}`)
.digest("hex");

const a = Buffer.from(expected);
const b = Buffer.from(sign);
if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return false;

const age = Math.abs(Math.floor(Date.now() / 1000) - Number(ts));
return age <= toleranceSec;
}
Did this answer your question?