For Support

What clinic staff might ask

"I don't see 'API Config' under Settings → Integrations." That's expected for almost everyone. The API Config tab is gated behind a company-level apiEnabled flag (packages/clinic-web/src/components/dashboard/settings/SettingsIntegrations.js:44) that is off by default and only turned on internally for clinics actively using the webhook integration. If a clinic asks for it, that's a request to escalate internally (it's set by Dentolize staff, not self-serve) — it is not a bug.

"The 'Type' field disappeared from my webhook row." This is expected after this PR ships. OTHER, NPHIES, and ZATCA used to be selectable, but all three always sent the identical payload — the field is removed because it never did anything. Any existing configuration continues to work unchanged; there's no migration needed since the stored records only ever used url / secret / apis to decide what to send.

"My webhook isn't receiving balance events." Walk through:

1. Is apiEnabled on for this company? (see above — if the API Config tab

isn't visible, nothing about webhooks works, full stop.)

1. Does the webhook row's APIs multi-select include "Balance Invoices"

and/or "Patient Balance"? Both must be explicitly checked — subscribing to "New Invoice" / "New Payment" does not also cover balance events; they are separate event types (NEW_BALANCE_INVOICE / NEW_BALANCE_PAYMENT).

1. Was the balance actually created via Add Balance or an overpayment

on an invoice? Balance added through other means (if any exist) won't fire these events — only those two code paths do.

1. Webhook delivery failures are silent by design — handleCallApi catches

and discards all errors (packages/server/src/apis/apiConfig/mutationsApiConfig.js, the outer try { ... } catch (e) { /* Ignored */ }). There is currently no delivery log or retry visible to support or the clinic. If a webhook URL is down, times out, or rejects the payload, Dentolize does not surface that anywhere — the balance top-up itself still succeeds normally. This is worth knowing so you don't go looking for an error message that doesn't exist.

"A patient's balance invoice has the wrong reference number" (pre-PR reports) This PR fixes a bug where, specifically for balance invoices created from an overpayment (not from Add Balance), the reference number could be written onto the wrong invoice object in the API response. See Payload accuracy fixes for the technical detail. If a report predates this fix shipping, it's the known bug; if it's after, treat it as a new issue.

A note on this walkthrough's sandbox

While preparing this documentation, the "Add Balance" action failed in the sandbox with a Prisma error because that sandbox company has no createdById set — a value the balance-invoice code has always required (both before and after this PR). If a real clinic ever hits Argument \id\ must not be null. on Add Balance or on an overpayment, the company record is missing its createdById — that's a data integrity issue to escalate to engineering, not something the clinic can fix from the UI.