Skip to content

Guides

Verify every webhook

Every event NezerCare sends carries a signature over the raw request body. Check it before you parse anything: an unverified webhook is just a request from the internet.

Add an endpoint in the dashboard under Integrations. Its signing secret is shown once, when you create it. Each endpoint has its own secret.

An address is https on a public DNS name: never an IP address, localhost or a .local name. NezerCare checks it when you save it and again before every delivery. It can send an Authorization header (bearer or basic) or a header of your choosing with each request, set when you add the address.

If NezerCare set an endpoint up for you while preparing your workspace, it stays paused until an owner or administrator selects Review and turn on beside it. Nothing is sent to it before that.

A Setup test endpoint is one NezerCare used to try your setup before you were invited: it gets only its made-up test patients' case and patient.deleted events, never a real patient's or an account event, and it's removed, with its deliveries, when your invitation is sent. The events and their bodies are the same as for any endpoint.

Headers

HeaderWhat it holds
x-nezer-event-idA UUID for this event, the same as the body's id. Retries reuse it, so deduplicate on it.
x-nezer-event-typeThe event, such as clinical_case.opened.
x-nezer-timestampWhen this attempt was signed, in seconds since the epoch. A retry is signed afresh, with a new timestamp.
x-nezer-signaturev1= and the HMAC-SHA256, in lowercase hex.
idempotency-keyThe same value as x-nezer-event-id.

Check the signature

The signature is the HMAC-SHA256 of <timestamp>.<raw body>, keyed with the endpoint's signing secret. Sign the raw bytes of the body, not JSON you parsed and serialized again, which can reorder keys or change spacing. Reject a timestamp more than five minutes from now.

Node.js
import { createHmac, timingSafeEqual } from "node:crypto";

export function isFromNezer(
  rawBody: string,
  headers: Record<string, string>,
  signingSecret: string,
): boolean {
  const timestamp = headers["x-nezer-timestamp"] ?? "";
  const provided = headers["x-nezer-signature"] ?? ""; // "v1=<hex>"

  // Seconds since the epoch; refuse anything more than 5 minutes off.
  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (!/^\d+$/.test(timestamp) || age > 300) return false;

  const hmac = createHmac("sha256", signingSecret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");
  const expected = Buffer.from(`v1=${hmac}`);
  const given = Buffer.from(provided);
  return given.length === expected.length && timingSafeEqual(given, expected);
}

Compare in constant time

Use timingSafeEqual or your language's equivalent, never ===. A plain comparison leaks timing that lets an attacker guess the signature byte by byte.

Deduplicate

Once the signature checks out, look up x-nezer-event-id among the events you've already handled. NezerCare retries a delivery that doesn't get a 2xx, so the same event can arrive more than once. Your handler must be safe to run twice.

Respond quickly

Return 2xx as soon as the event is stored durably (a queue row, a database write), then do the slow work (creating a ticket, notifying a clinician) afterwards. A handler that waits on slow work is treated as failing and retried.

What counts as a failure, and the retries. Any status that isn't 2xx, a redirect (NezerCare doesn't follow redirects), a connection that can't be made and no answer in time all fail the attempt. The retry is scheduled 2 seconds later, then 4, 8, 16 … doubling up to 1,024 seconds (about 17 minutes) between tries. After 12 attempts, about 51 minutes after the first, NezerCare stops and the delivery stays failed until someone on your team sends it again from the dashboard.

Answer within 5 seconds. A request that gets no answer in 5 seconds is a timeout. An address that times out ten attempts in a row, over at least ten minutes, is paused: NezerCare stops sending to it and tells your team in Integrations (the address shows as Paused: not answering) and in Operations, in the Integration queue. Nothing is lost while it is paused. Once your receiver answers again, press Resume and what waited is sent. Any answer, even an error, ends a run of timeouts.

Ten addresses a workspace. A workspace can have up to 10 webhook addresses (remove one you no longer use, or send several kinds of event to one address); the 11th is refused with 409 WEBHOOK_ENDPOINT_LIMIT. Deliveries are shared fairly between workspaces, and at most 3 of one workspace's are sent at the same moment, so a slow receiver delays your own events a little and never another workspace's.

Event bodies can contain protected health information. Don't write them to ordinary logs.

Test your address

Test connection beside an address in Integrations → Connection health sends it a message built like a real event: the same headers, a valid signature made with that address's own signing secret, and the login you gave the address (an Authorization or API-key header), so your receiver sees exactly what a delivery shows it. The body is { "type": "integration.test", "data": { "test": true, … } } and the x-nezer-test: true header is set. It carries no patient data and creates nothing in NezerCare. Answer 2xx and do nothing else with it. It is not an event you subscribe to, it is sent once and not retried, and your team sees the status your system answered with. A 401 means your receiver didn't accept the signature or the login.

Events

EventSent when
clinical_case.openedA signed-in patient's concern, or a request your team made of @Nezer in Slack, needs a clinician. Carries what the patient wrote, the matched red flags, the priority and the source (staff_slack when your team raised it, with no patient notes). A patient's concern carries healthConcerns, the version of your Health concerns it was triaged on, and intake, the follow-up and safety questions NezerCare asked and the patient's answers (see the clinical cases guide).
clinical_case.patient_message_createdThe patient wrote in a case conversation. Holds the patient's words.
conversation.message_createdA message was added to a conversation of your own patient portal (the patient messaging API): the patient's, NezerCare's or your care team's. Holds the patient's words. Not ordered: apply messages by their sequence.
conversation.updatedA portal conversation's status, care status, 911 flag or what it awaits changed with no message to carry it. Holds no message text.
clinical_case.acknowledgedA member of your team acknowledged the case in NezerCare. Not the same as your processed update.
clinical_case.resolvedA member of your team resolved the case in NezerCare. A resolution your own system reports with a resolved update sends no event. The body is the same as clinical_case.opened, with the case's status and its resolution outcome and note.
patient.deletedYour team deleted a patient's data in NezerCare. Carries only the patientId, the workspace ID (environmentId), a reason code and the time, so your system can delete or close its copy.
billing.usage_threshold_reachedUse reached 80%, 95% or 100% of the month's credits, once each a month. Carries the credits used, the month's credits, what's left and whether Nezer is paused. No patient data.
subscription.updatedYour subscription changed state: a payment, a failed payment, the end of a grace period, a cancellation, or an Enterprise invoice paid or overdue. Carries the status and the plan. No patient data.

Until your organization signs its BAA, every event about patients (the case events, the portal conversation events and patient.deleted) is held, not dropped, and goes out once it's signed. Account events are never held. Payloads are in the webhook events reference.