No. Calendly does not present rescheduling as a separate webhook event type. The documented pattern is an invitee.canceled event for the old booking followed by an invitee.created event for the new booking. The old and new invitee records provide the link that lets a clinic reconcile one reschedule instead of counting two bookings.
What does Calendly send during a reschedule?
Calendly’s webhook guide shows that an invitee who reschedules causes the original invitee to be canceled and a new invitee to be created. The new payload includes a relationship to the old invitee. The help documentation describes the same relationship from the user’s point of view.
That means an integration should not search only for an event named rescheduled. It should consume the two documented events, persist both payloads in a bounded audit record, and apply a reconciliation rule. If the first event arrives without the second, the appointment should be marked pending reconciliation rather than permanently canceled.
The reschedule webhook comparison shows why vendor-specific event names cannot be generalized. Calendly’s model is its own contract.
How should a clinic join the old and new bookings?
Store the Calendly invitee URI or identifier, the event URI, the event type, the received timestamp, and any old_invitee or new_invitee reference supplied by the payload. Then make the new invitee point to the previous internal appointment or attribution record.
Do not use the patient’s name or time alone as the join key. Two patients can share a name, and a reschedule changes the start time. A stable vendor identifier plus a tenant-scoped internal ID is safer and easier to audit.
Local field
Purpose
vendor_invitee_id
Unique Calendly invitee reference
previous_invitee_id
Old invitee referenced by a reschedule
appointment_id
Internal booking identity that survives time changes
lifecycle_state
Booked, canceled, rescheduled, or needs review
source_attribution_id
Approved marketing source record without clinical detail
What if events arrive out of order?
Webhooks are messages delivered over a network, not a synchronous database transaction. The new invitee can arrive before the canceled event, or a retry can deliver an event more than once. A handler must be idempotent and able to reconcile later.
Verify the webhook signature and tenant routing.
Record an event ID or deterministic fingerprint before applying side effects.
Upsert the vendor invitee record.
Resolve old and new references when both are available.
Update the internal appointment once, preserving its attribution identity.
Send unresolved references to a review queue instead of guessing.
The webhook retry article covers the same need for explicit acknowledgement and retry handling. A 200 response means the receiver accepted the message, not that the booking was reconciled correctly.
How should reporting count a reschedule?
Count one booking journey, not two new patients. Keep a status history that records the original time, the cancellation event, the replacement time, and the final appointment state. If the clinic optimizes Google Ads for booked appointments, the reschedule should normally update the existing outcome rather than create a second conversion.
That reporting rule is an internal measurement choice. A clinic may define separate events for booked, attended, or completed, but each event needs a stable transaction ID and a clear deduplication rule. The booking outcome taxonomy helps keep those states separate.
What data should the webhook handler avoid?
Store only fields needed for scheduling, reconciliation, attribution, and audit. Do not copy free-text intake answers, treatment notes, diagnoses, or payment details into a webhook log. Keep the raw payload in a protected store only when the contract and retention plan require it, and redact sensitive values from ordinary application logs.
A booking integration can prove that a slot changed without exposing the patient’s entire record to a marketing dashboard. The internal appointment ID and vendor reference are usually more useful than a copied patient profile.
FAQ
Does invitee.canceled mean the patient is lost?
Not necessarily. When a reschedule follows, the old invitee is canceled as part of the transition.
Can the new invitee be treated as a new lead?
Only when the clinic’s business rule says so. The vendor relationship normally indicates a continuation of the same booking journey.
What if the old invitee reference is missing?
Hold the event for reconciliation. Do not join by name and time alone.
Should a browser conversion fire twice?
Not for the same internal booking outcome. Use a stable transaction ID and an explicit reschedule rule.
Not legal advice: This article describes webhook behavior and an integration pattern. Review privacy, retention, and healthcare obligations for the actual clinic and vendors.
Google Calendar can return an event that starts before timeMin because events.list uses overlap boundaries. The API defines timeMin as an exclusive lower bound on an event’s end time. It defines timeMax as an exclusive upper bound on an event’s start time.
Those definitions do not mean “event start must fall inside the window.” They mean an event can qualify when it overlaps the window. A 9:30 to 10:30 appointment can appear in a request bounded from 10:00 to 11:00 because its end is after 10:00 and its start is before 11:00.
What do timeMin and timeMax actually filter?
The events.list reference describes timeMin as the exclusive lower bound for an event’s end time. An event must end after that instant to qualify. An event that ends exactly at timeMin does not pass that boundary.
The same reference describes timeMax as the exclusive upper bound for an event’s start time. An event must start before that instant. An event that starts exactly at timeMax does not pass.
With both parameters present, the practical overlap test is event.end > timeMin and event.start < timeMax. That expression follows directly from Google’s two parameter definitions. It includes events crossing either inner edge while excluding events that only touch the outside boundary.
This behavior is separate from a Google Calendar FreeBusy error. FreeBusy reports occupancy intervals and can return per-calendar errors. events.list returns event resources under its own filtering contract.
Why does an event starting before timeMin still appear?
Consider a request from 10:00 to 11:00. An appointment starts at 9:30 and ends at 10:30. Its end is later than timeMin, and its start is earlier than timeMax. It overlaps the first half hour of the requested window, so the API includes it.
Now consider an appointment from 9:00 to 10:00. Its end equals the exclusive timeMin boundary. It does not occupy any time after 10:00, so it is excluded. An appointment starting at exactly 11:00 is also excluded because its start equals the exclusive timeMax boundary.
An event that starts at 10:30 and ends at 11:30 qualifies. Its start is before 11:00, even though its end falls outside the requested window. The API is finding events that intersect the interval, not events fully contained by it.
Operational inference: keep this overlap test in one shared calendar adapter and test both boundary-equality cases. Refiltering results by start time in a later service can erase valid conflicts that began before the visible booking window.
Does every returned event block appointment availability?
No such conclusion follows from events.list alone. The method returns event resources that match the request. Whether a result blocks a clinic slot depends on the application’s approved rules for event status, transparency, ownership, event type, calendar coverage, and scheduling policy.
Operational inference: separate retrieval from occupancy classification. First collect every event that overlaps the window under Google’s boundaries. Then apply a documented rule that decides which events block availability. Keep rejected events visible in diagnostic counts without copying their descriptions or attendee details into general logs.
A returned event also does not prove that every relevant calendar was queried. The article on secondary Google calendars in Jane shows how calendar coverage can be narrower than staff expect. Confirm calendar scope before declaring a provider free.
If the integration uses FreeBusy for occupancy, fail closed on per-calendar errors rather than converting an indeterminate response into open capacity. If it uses event resources, document the event fields that inform the block decision. Do not mix the two contracts in one success flag.
How do time zones affect the overlap window?
Google requires RFC3339 timestamps with a mandatory time zone offset for both parameters. The examples in the reference include an explicit numeric offset and UTC with Z. Milliseconds may be supplied, but Google says they are ignored.
The comparison concerns instants, not the clock labels shown to staff. A window expressed in one offset can overlap an event represented in another offset after both are normalized. Building bounds from a clinic’s local wall time without the intended offset can query a different interval.
Operational inference: derive the booking window in the clinic or provider time zone, convert it to RFC3339 with an explicit offset, and retain that zone context for display. Test daylight-saving transitions for every zone the product supports. Avoid using a server’s default zone as an unstated scheduling rule.
The optional timeZone parameter controls the time zone used in the response. If it is omitted, Google uses the calendar’s time zone. That response choice does not change the need to send valid, explicit offsets in timeMin and timeMax.
What changes when recurring events are involved?
The singleEvents parameter determines whether recurring series are expanded into instances. Its default is false. When true, the response contains one-off events and expanded instances rather than the underlying recurring event records.
Operational inference: a booking conflict check that needs occupied occurrences should choose its recurrence strategy explicitly. Do not assume that the default response has already expanded every appointment occurrence that intersects the requested period.
Use synthetic recurring events to test an occurrence that begins before timeMin, an exception moved into the window, and a cancelled instance. Verify the exact response shape under the chosen singleEvents and deletion settings before relying on it for capacity.
Can time bounds be reused with incremental synchronization?
No. The events.list reference says a request using syncToken cannot also specify timeMin, timeMax, updatedMin, iCalUID, orderBy, q, or the listed extended-property filters. Other parameters should remain the same as the initial synchronization.
A windowed query and an incremental mirror serve different jobs. The first asks which events overlap a period under the supplied bounds. The second asks which resources changed after a stored synchronization state. Combining their parameters is not a supported shortcut.
If a sync token expires, Google returns HTTP 410 and instructs the client to clear its synchronized store and run a full sync without that token. Recovering from Google Calendar 410 Gone covers that state transition in detail.
Operational inference: maintain one coherent calendar mirror with its sync cursor, then run overlap checks against that mirror or issue a separate bounded query. Do not silently fall back from a failed sync request to an empty result, because an empty result can be misread as open availability.
How should an overlap reconciliation test be designed?
Create synthetic events around a fixed window. Include one event wholly before it, one ending exactly at timeMin, one crossing timeMin, one inside the window, one crossing timeMax, one starting exactly at timeMax, and one wholly after it.
The expected included set contains the three events with positive overlap: the one crossing the lower bound, the one inside, and the one crossing the upper bound. Equality at either exclusive outer boundary does not qualify. Run the same cases with explicit offsets that represent the same instants.
Operational inference: record only synthetic calendar aliases, event fingerprints, normalized timestamps, request parameters, and inclusion results. Avoid patient names, attendee addresses, descriptions, or clinical notes. A conflict detector should not need those fields to prove interval behavior.
If the workflow later updates a reconciled event, protect newer edits with the conditional-write pattern described in Google Calendar ETag and If-Match handling. Correct overlap retrieval does not prevent a stale worker from overwriting a later change.
Frequently asked questions
Is timeMin a lower bound on event start time?
No. Google defines timeMin as the exclusive lower bound on an event’s end time. Events that begin earlier can still appear when they end after the boundary.
Is timeMax an upper bound on event end time?
No. Google defines timeMax as the exclusive upper bound on an event’s start time. An event can end later and still qualify when it starts before that boundary.
Does an event ending exactly at timeMin appear?
No. The bound is exclusive. An event whose end equals timeMin does not pass the documented lower-bound condition.
Can timeMin and timeMax be sent with syncToken?
No. Google lists both time parameters among those that cannot be combined with syncToken in an incremental synchronization request.
NexHealth can return the intended time and still write an appointment with the wrong EHR appointment type or procedure code. The two outcomes come from different records. A NexHealth appointment type controls scheduling. An appointment descriptor represents an EHR-native appointment type or procedure code used when the appointment is written to the connected system.
The practical failure is easy to miss because the booking itself can succeed. If the NexHealth appointment type has no mapped descriptor, NexHealth says the appointment can land in the EHR with the practice’s default appointment type. The office may then need to correct the EHR record manually.
What is the difference between an appointment type and a descriptor?
NexHealth describes appointment types as its own scheduling construct. They are not read from or written to the target EHR. A product can create types such as a cleaning, exam, or root canal, assign a duration, and attach each type to selected working hours. Those records answer what a provider can be booked for and when.
Appointment descriptors come from the EHR. NexHealth uses that term for EHR-native appointment types and procedure codes exposed by supported integrations. A descriptor can determine how a booked visit appears in the practice system and which code reaches downstream office processes.
Similar names do not make the records interchangeable. A NexHealth type named “Cleaning” and an EHR type named “New Patient Cleaning” remain separate entities. One organizes the booking interface. The other controls the EHR write. Matching their labels in application code does not create the documented mapping.
This distinction also separates the present issue from NexHealth returning no available slots. Missing slots concern working hours, calendar unavailability, and type assignment. A wrong EHR code appears after a slot has already been selected.
How can the correct time produce the wrong EHR type?
The scheduling guide explains that /available_slots uses an appointment_type_id to narrow eligible working hours and set slot length. Appointment descriptors do not participate in that calculation. A slot can therefore be correct even when the selected NexHealth type has no descriptor mapping.
When the application later posts the appointment with that type, NexHealth adds the associated descriptors to the EHR write. If no descriptor is mapped, the guide says the appointment uses the practice’s default EHR appointment type. That default may differ from the service chosen by the patient or staff member.
The result is not evidence that availability calculation failed. It shows that slot selection and EHR localization passed through different configuration layers. Repeating the availability request will not repair the missing descriptor relationship.
Appointment creation has its own separate guard. NexHealth v3 appointment validation explains why an accepted POST is not proof that a time was inside working hours. That rule does not replace descriptor mapping either.
How should descriptors be retrieved and mapped?
NexHealth provides GET /locations/{id}/appointment_descriptors for the descriptors available at one location. The location scope matters. Its scheduling guide warns that codes may be shared conceptually across practices while their NexHealth descriptor identifiers can differ by location.
After retrieving the intended descriptor, associate its identifier with the NexHealth appointment type through emr_appt_descriptor_ids. NexHealth documents this mapping on the appointment type. Subsequent appointments posted with that appointment_type_id include the mapped EHR-specific type or procedure code.
Do not infer the identifier from the visible code label, copy it from another location, or keep an old identifier after an EHR migration. Retrieve the current location’s supported descriptors and have the practice confirm which EHR type or code represents each offered service.
Operational inference: store the mapping with institution, location, NexHealth appointment type, descriptor identifier, descriptor kind, review date, and an approved status. Reject or hold a booking path when the required mapping is absent instead of guessing from a similar name.
Does every connected EHR support the same descriptors?
No. The descriptor endpoint lists separate sets of integrations for procedure codes and EHR-specific appointment types. Support for one descriptor kind does not establish support for the other, and a connector absent from the current list should not be treated as compatible because another connector returned similar data.
The supported list is a current vendor capability statement. Review the live endpoint documentation before enabling descriptor-dependent booking for a clinic. A configuration that worked under one EHR should be reviewed again after a connector, location, or practice-system change.
Operational inference: gate descriptor-dependent services by the connected integration and descriptor response. The interface should not promise a procedure-specific EHR write when the current connector cannot provide or accept the required descriptor type.
Rescheduling support is another independent capability. The article on NexHealth PATCH rescheduling by EHR covers which systems support direct time and operatory changes. A connector can support one workflow without supporting every booking feature.
What should the integration verify after booking?
A successful response should be followed by reconciliation against the approved scheduling record. Compare the returned appointment identifier, institution, location, provider, operatory when relevant, start and end times, NexHealth appointment type, and the EHR type or procedure code expected for that service.
Operational inference: define the expected descriptor before submission and compare it with the resulting appointment through the authorized integration path. If the EHR shows its default type instead, mark the booking for correction. Do not report the procedure mapping as successful merely because the time appears on the calendar.
Keep the evidence narrow. A reconciliation log can use approved internal identifiers, system aliases, descriptor identifiers, timestamps, and result categories. Patient names, contact details, appointment notes, and clinical information do not belong in general application logs or marketing systems.
If several operatories can serve the same clock time, preserve the selected slot record as a unit. NexHealth operatory availability explains why an identical displayed time does not make different slot records equivalent.
How can teams test the mapping without using patient data?
Use an authorized test environment and synthetic appointments. Retrieve descriptors for the exact test location, map one approved NexHealth appointment type, request a suitable slot, and create the synthetic booking. Then inspect the connected EHR through the approved path and confirm that the intended native type or code is present.
Run a controlled negative case too. Use a synthetic appointment type with no descriptor only where the clinic and test environment permit it. Confirm whether the practice default appears, then remove or correct the test record. The purpose is to identify the fallback, not to leave ambiguous appointments in an operational calendar.
Operational inference: repeat the test for every location and every descriptor-dependent service that will be offered. A passing result at one location does not validate a copied identifier elsewhere. Record only synthetic identifiers, expected mapping, observed mapping, connector, and review date.
What should happen when the mapping is missing or wrong?
Stop treating the service as ready for automated EHR write. Retrieve the current descriptors for the affected location and ask the authorized practice owner to confirm the intended native type or code. Update the appointment-type mapping only after that confirmation.
Operational inference: route already-created mismatches to a bounded reconciliation queue. Each item should identify the appointment through an approved internal reference, show expected and observed descriptor identifiers, name the location, assign an owner, and record the correction result.
Do not silently replace the appointment, cancel it, or create another booking to repair a code mismatch. Those actions can affect identity, availability, notifications, and reporting. Correct the record through the clinic’s approved workflow and verify the final EHR state.
If the connector or mapping changed during deployment, pause the affected service rather than applying an identifier from memory. The cost of asking for confirmation is lower than publishing a procedure-specific booking path that writes the practice default.
Frequently asked questions
Does a NexHealth appointment type come from the EHR?
No. NexHealth states that appointment types are its own constructs and are not read from or written to health record systems. EHR-native types and procedure codes are appointment descriptors.
Do descriptors determine which slots are available?
No. NexHealth says slot calculation uses working hours, calendar unavailability, and the requested appointment type. Descriptors matter when the appointment is written to the EHR.
What happens when no descriptor is mapped?
The scheduling guide says the appointment can land in the EHR with the practice’s default appointment type. That default may not match the service intended by the booking application.
Can one location’s descriptor ID be reused at another location?
Do not assume so. NexHealth notes that descriptor identifiers may differ by location. Retrieve and verify descriptors for the exact location used by the appointment.
Jane does not notify a patient waiting for a 60-minute appointment when only a 30-minute appointment is cancelled. Its troubleshooting guide says Wait List Notifications consider appointment types with the same or a shorter scheduled length than the cancelled appointment. Free time beside that cancelled slot is not combined to make a longer opening.
This can look wrong on a schedule with plenty of white space. Jane is evaluating the duration of the cancelled appointment, not every adjacent gap visible to staff. Check that rule first, then investigate shifts, online-booking settings, tags, resources, breaks, and notification preferences if the requested duration should fit.
Why does a 30-minute cancellation exclude a 60-minute request?
Jane’s guide states that Wait List Notifications trigger only for requested appointment types whose scheduled length is equal to or shorter than the cancelled appointment. A 30-minute cancellation can therefore match a 30-minute or shorter request, but not a 60-minute request.
The system does not look beyond that cancelled block and join it with neighboring free time. The guide gives this exact boundary even when the staff member has open time immediately after the cancellation. The available schedule may appear long enough to a person, while the notification rule still sees only the released appointment length.
Do not change the patient’s requested appointment type to a shorter one merely to make the notification fire. Duration belongs to the service the clinic intends to book. If staff can safely offer another type, that decision should follow the clinic’s approved scheduling process.
Does a visible wait-list opening make every patient eligible?
No. Jane can show a Wait List Notification block while some patients remain ineligible. The system evaluates the request against the released appointment and other clinic settings.
Duration is one filter. A requested appointment may also require a resource that is not available. A tag on the appointment type may not match the tag on the shift, or the requested type may have been archived. In those cases, another patient can be eligible even though the patient being investigated receives nothing.
Patient communication preferences matter too. Jane says Do Not Text or Do Not Email on the profile blocks the corresponding wait-list notification.
Operational inference: troubleshoot one patient, appointment type, staff member, and cancelled slot at a time. A clinic-wide statement such as “the wait list is broken” hides the eligibility decision that needs to be checked.
Which schedule settings can suppress the notification?
The staff member needs a shift beneath the cancelled appointment. If the shift is configured as Contact to Book or Not Bookable Online, Jane says no Wait List Notification is triggered. The same symptom can therefore come from shift configuration rather than appointment duration.
A cancellation inside the clinic’s Do Not Allow Booking Within period also prevents the notification. Jane’s broader FAQ describes a manual route when the clinic uses the related contact-to-book option, but automatic notification should not be assumed inside that restricted period.
Breaks can block the released time. Jane recommends checking the Appointments Report for breaks, including deleted breaks, at the day and time in question. Cluster Online Booking and Make Me Look Busy can also affect whether the released slot qualifies under the staff member’s online-booking setup.
Do not solve these conditions by switching off every constraint. Each setting may reflect a real clinic rule. Identify which rule excluded the request and decide whether the current configuration is intentional.
How should Contact to Book cases be interpreted?
If the staff member’s shift itself is Contact to Book or Not Bookable Online, Jane says no Wait List Notification is triggered. When the requested appointment type is Contact to Book, the behavior is different: a notification block can appear for administrative handling, but automatic notification does not normally trigger when all matching requests are Contact to Book.
Jane documents an exception when at least one eligible patient requested a Bookable Online type. In that situation, notifications can be sent to all eligible patients, including those who requested a Contact to Book appointment.
This distinction is easy to miss because the same phrase appears at the shift and appointment-type levels. Record which object carries the setting before changing it.
Operational inference: present separate diagnostic labels for shift booking mode and requested-type booking mode. Staff should not have to infer the source from a generic “not eligible” result.
What is a practical troubleshooting order?
Begin with the facts closest to the reported symptom. Confirm the cancelled appointment’s scheduled length and the requested appointment type’s length. If the request is longer, the documented duration rule explains the exclusion even when adjacent free time exists.
Confirm that Wait List Notifications are enabled for the clinic’s eligible plan.
Compare the requested duration with the cancelled appointment duration.
Verify that the staff member has a shift under the cancelled time.
Check shift and appointment-type online-booking modes.
Check the restricted booking window, tags, required resources, and archived state.
Look for a break and relevant clustering or availability-display settings.
Confirm the patient’s email and SMS preferences and suppression settings.
Stop when a documented rule explains the result. Changing several settings at once makes the cause harder to prove and may expose openings the clinic intended to keep private.
Reminder ownership is separate from wait-list eligibility. See preventing duplicate appointment reminders before enabling another sender to compensate for a Jane notification that was correctly suppressed.
How can the clinic test the duration rule?
Use synthetic patients and appointment types in an authorized test setup. Create a staff shift with a controlled sequence of appointments and gaps. Add one 30-minute wait-list request and one 60-minute request with matching availability.
Cancel a 30-minute appointment. The test should show that the shorter request can qualify while the 60-minute request does not, even if another 30 minutes is free immediately after the released slot. Then cancel a 60-minute appointment and repeat the comparison.
Change one additional rule per test. Add a required resource that is unavailable, introduce a tag mismatch, place a break over the slot, or move the cancellation inside the restricted booking window. This isolates each reason instead of producing one opaque failure.
Use controlled email and SMS destinations. Do not put real names, phone numbers, appointment reasons, diagnoses, or clinical notes into the test. Record the rule evaluated, expected eligibility, notification route, and observed result.
What should staff tell a patient?
Staff can explain that the released appointment did not match the duration or booking rules of the patient’s request. Avoid saying the patient lost a reserved appointment unless the clinic has evidence that a specific reservation existed.
A wait-list request is not a completed booking. Keep the patient on the list according to clinic policy, adjust preferences only with authorization, and offer an approved manual booking path when appropriate.
Do not count the notification as attendance or even confirmation. Measure wait-list offers, claimed openings, completed bookings, cancellations, and attendance as separate states. The article on calculating no-show rate by booking source explains why finalized outcomes need their own denominator.
Communications should also remain distinct by purpose. Appointment reminders versus intake reminders shows why a wait-list opening should not become an unrelated request for forms or clinical information.
What evidence helps resolve repeat reports?
Keep a minimal operational record: synthetic or internal request reference, appointment type, requested duration, cancelled duration, staff shift, booking mode, tag and resource result, restricted-window result, notification preference result, and final eligibility reason.
Do not place patient names, contact details, treatment notes, diagnoses, or full message contents in general troubleshooting logs. Authorized staff can inspect the patient profile in Jane when needed under clinic policy.
Operational inference: report exclusions by rule. A count of longer-duration requests excluded after shorter cancellations can reveal a scheduling mismatch without exposing patient details. Jane does not prescribe clinic-specific thresholds or operational targets for that report.
Frequently asked questions
Will Jane combine a 30-minute cancellation with the free 30 minutes beside it?
No. Jane’s guide says it considers only what fits within the cancelled appointment time, not adjacent free time.
Can a 30-minute patient be notified after a 60-minute cancellation?
Duration alone permits that match because the requested appointment is shorter. Other rules, including shifts, resources, tags, booking windows, and notification preferences, can still make the patient ineligible.
Does a Wait List Notification block mean every patient will be notified?
No. Some patients may fail an eligibility rule while others match the same released slot.
Should staff shorten the appointment type to trigger a notification?
No. Appointment length should reflect the service the clinic intends to book. Change it only through the clinic’s approved scheduling process.
NexHealth documents appointment rescheduling through PATCH /appointments/{id}, but the capability is not available for every connected health record system. Its current endpoint reference says changes to start_time, end_time, operatory_id, or note are supported only for Dentrix, Dentrix Enterprise, Eaglesoft, and Open Dental.
A product that exposes the same reschedule button for every NexHealth institution can therefore promise a write that the connected EHR does not support. Check the actual EHR capability before showing or executing the action. When the write is unsupported, route staff to the clinic’s approved native scheduling workflow rather than treating an API failure as a completed reschedule.
Which appointment fields can NexHealth PATCH?
The endpoint reference lists confirmed, cancelled, checkin_at, start_time, end_time, operatory_id, and note as patchable fields. It warns that updates to other fields will be overwritten when NexHealth synchronizes data from the health record system.
That warning matters even when an API representation appears to accept more properties. A field visible in a response is not automatically a supported write field. Build the request from an allowlist based on the endpoint documentation, not by serializing the complete appointment object back to the API.
Confirmation and check-in have additional transition limits. NexHealth says confirmation can move only from false to true, while checkin_at can move only from null to a date-time value. Do not model either property as a freely reversible toggle.
Creation has a different validation boundary. NexHealth appointment creation outside working hours explains why a create request must be checked against available slots. That does not establish that a later reschedule is supported by the connected EHR.
Which EHRs support direct rescheduling?
NexHealth currently names Dentrix, Dentrix Enterprise, Eaglesoft, and Open Dental. For those systems, the reference says an existing appointment can be updated directly through PATCH for start_time, end_time, operatory_id, and note.
The list is a product capability statement, not a guess based on the appointment schema. If a clinic uses another EHR, do not infer support because the same endpoint exists, the fields appear in a response, or a sandbox accepted a request under a different integration.
The documentation can change as NexHealth adds or removes support. Treat the list as versioned vendor configuration. Review the current endpoint reference before release and whenever the integration type changes.
Operational inference: maintain a server-side capability gate keyed to the connected EHR and the action, not a broad flag named “NexHealth enabled.” Availability reads, appointment creation, confirmation, cancellation, check-in, and rescheduling are separate capabilities.
Why should the interface be gated before submission?
A visible reschedule control tells staff that the product can complete the change. Waiting for an API error after they choose a new time creates an ambiguous state: the receptionist may believe the appointment moved while the EHR still shows the original slot.
Operational inference: check the EHR capability before presenting the action. If direct rescheduling is unsupported, explain that the change must be completed in the approved source system. Do not silently create a second appointment or cancel and recreate the original unless the clinic and vendor have approved that distinct workflow.
Keep capability decisions on the server as well as in the interface. A hidden button does not protect an API route, a queued job, or an older client. The worker should reject unsupported writes before constructing a patient-bearing request.
A clinic may map by operatory, provider, or another scheduling dimension. The article on NexHealth availability across operatories shows why an identical clock time does not make two slot records interchangeable.
How should a supported reschedule be prepared?
Start with the appointment identifier and the clinic’s current source-of-record state. Confirm that the connected EHR is on NexHealth’s supported list for direct rescheduling. Then build a PATCH body containing only the intended documented fields.
A time change should keep start_time and end_time coherent. An operatory change should use the operatory selected for that appointment and location. Do not copy unrelated fields from a cached response merely because they are present.
Operational inference: validate the requested destination against the clinic’s current scheduling rules before sending the write. The endpoint’s reschedule support list says which EHR connectors can accept those updates. It does not state that every requested destination remains available or appropriate at submission time.
The endpoint reference documents HTTP response categories for the PATCH request, but a booking workflow still needs to verify the final state used by clinic staff. An HTTP response proves what the API returned for that request. It does not prove that every downstream calendar, reminder, or reporting view has already reconciled.
Operational inference: retrieve or observe the resulting appointment through the approved integration path and compare its identifier, start, end, operatory, and relevant state with the intended change. Mark the operation complete only after the workflow’s defined verification passes.
Do not use a marketing or analytics callback as scheduling proof. The appointment system and connected EHR own operational status. Reporting systems should receive only approved outcome fields after reconciliation.
Preserve original booking-source attribution across the change. A reschedule performed through NexHealth is an action channel, not necessarily the source that acquired the appointment. See preserving original booking source after a reschedule.
How should unsupported reschedules be handled?
Stop before sending the unsupported PATCH. Tell the authorized staff member which system must be used to complete the change. Keep the original appointment state unchanged in the product until verified state returns from the EHR or the approved reconciliation process.
Do not translate a reschedule into cancellation plus creation by default. That sequence can change appointment identity, notifications, reporting, and clinic workflow. NexHealth’s PATCH reference does not authorize that substitution.
Operational inference: create an exception record with the clinic, EHR type, appointment reference, requested action, reason the API path is unavailable, assigned owner, and resolution status. Keep patient names, notes, contact details, and clinical information out of general exception logs.
If the EHR changes later, re-evaluate capabilities instead of carrying the previous connector’s settings forward. A supported action under Open Dental does not prove the same action works after a clinic migrates to another system.
How can the workflow be tested safely?
Use synthetic appointments in authorized test environments for each supported connector available to the team. Test time, duration, operatory, and note changes separately so the result identifies which capability failed.
For an unsupported connector, verify that the interface does not offer the direct action and that the server rejects a forced request before it reaches NexHealth. Confirm that the fallback instructions point staff to the correct approved workflow without claiming that the appointment already moved.
Test the one-way fields as well. A confirmation request should follow the documented false to true path, and check-in should move from null to a date-time. The product should not present unsupported reverse transitions.
Use neutral synthetic notes and contacts. Record connector type, appointment fingerprint, attempted fields, response category, verification result, and elapsed time. If webhook delivery forms part of the local verification design, also test its failure path using NexHealth webhook endpoint deactivation.
What should be monitored?
Monitor blocked actions by EHR, PATCH response category, verification mismatch, time to reconciliation, repeated attempts, and requests containing fields outside the allowlist. Alert when the configured connector type is missing or disagrees with the institution record used for the request.
Do not measure success only by the absence of API errors. A control that blocks unsupported writes is working when it prevents the request and routes it for the correct manual action. Track that result separately from a technical failure.
Review the capability map when NexHealth changes its documentation and before enabling a new clinic. Record the reviewed documentation version or date. Avoid promising permanent support for any connector based on one successful test.
Frequently asked questions
Can NexHealth PATCH appointment times for every EHR?
No. The current reference names Dentrix, Dentrix Enterprise, Eaglesoft, and Open Dental for direct updates to time, operatory, and note.
Can I PATCH any field returned on the appointment?
No. NexHealth lists the patchable fields and says other field updates will be overwritten during synchronization with the health record system.
Can confirmation be changed from true back to false?
Not through the documented transition. The reference says appointment confirmation can be patched only from false to true.
Should an unsupported reschedule become cancel and recreate?
Not by default. That is a different workflow with different identity and communication effects. Use it only if the vendor and clinic have explicitly approved and tested it.
A booking integration can overwrite a newer Google Calendar edit when it sends an update based on an old copy of the event. Google Calendar exposes an etag for each resource version. Send the previously retrieved value in the If-Match header when updating or deleting an event. If someone changed the event after your read, Google returns HTTP 412 Precondition Failed instead of applying the stale write.
A 412 is a conflict signal, not permission to repeat the same request without the condition. Fetch the current event, compare the changes, and decide which fields can be reapplied. This protects a receptionist’s newer time, status, or note from a background worker that is still holding an earlier event version.
How does a stale booking update overwrite a newer edit?
Consider two actors working on one calendar event. A scheduling integration retrieves the event at version A. A staff member then edits the event in Google Calendar, creating version B. If the integration later sends its full copy of version A as an unconditional update, fields from the staff member’s change may be replaced by the stale values.
The problem is timing, not necessarily a bad payload. Both actors may have made valid changes. The integration simply did not prove that the version it read was still current when it wrote.
Google’s resource-version guide describes conditional modification as the mechanism for this case. The client retrieves an etag, includes that value in If-Match, and asks Google to modify the resource only if the version has not changed in the meantime.
This issue is separate from incremental synchronization. An expired sync cursor requires the recovery covered in Google Calendar 410 Gone during appointment sync. An etag conflict concerns one resource version at write time.
What does If-Match change?
Without a matching condition, the server evaluates the update under the endpoint’s ordinary rules. With If-Match, the client states which event version it intends to modify. Google compares the supplied value with the current resource etag.
If the values match, the modification succeeds and Google returns the new resource version with a new etag. If they do not match, Google returns 412. The older request does not silently replace the newer server state.
Use the etag from the same event version that supplied the fields used to construct the update. Do not fetch an etag in a separate step and attach it to a payload built from an older cache. That would prove only that the separately fetched version was current, not that the payload represented it.
Operational inference: store the event identifier, retrieved etag, and local source version together for the duration of the write. A queue job should either carry that coherent version tuple or fetch and rebuild its intended change immediately before submission.
What should happen after HTTP 412?
Google says clients can retrieve the resource again and reapply their changes. That does not mean every field from the stale copy should be copied onto the current event. Reapplying should mean reconstructing the intended change against the latest server version.
First retrieve the current event. Then compare the integration’s intended fields with the fields that changed on the server. A simple nonconflicting change may be safe to reapply. A changed appointment time, cancellation state, calendar ownership, or another scheduling decision may require an operator or an authoritative source-of-record rule.
Operational inference: classify conflicts by field and source. If the worker intended to add an internal correlation property while staff changed the start time, it may be possible to apply only the property to the new version. If both sides changed the start time, automatic last-write-wins behavior hides a real scheduling conflict.
Set a retry ceiling. A resource that changes repeatedly can produce several 412 responses. After the limit, move the operation to a visible reconciliation queue. Do not remove If-Match to make the error disappear.
Should update, delete, and insert use the same rule?
Google documents conditional modification for updates and deletes. Both operations can include If-Match when they should proceed only against the version previously retrieved.
Insert is different. Google’s guide says conditional modifications are not supported for insert operations. When an API operation allows the client to supply a resource ID, Google instead guarantees that creation succeeds only if no existing entry has that ID.
Do not turn that statement into a universal booking-idempotency claim. The application still needs a documented event-ID strategy, request retry behavior, and reconciliation process. The resource-version guide establishes the conditional-modification boundary, not the clinic’s complete creation contract.
A delete also deserves care. A stale delete may target an event that staff rescheduled or otherwise changed after the integration’s read. Sending the old etag in If-Match makes that later edit visible as a conflict rather than erasing it.
How should event versions be stored?
Store the latest known etag beside the corresponding Google event identifier in the calendar mirror. Replace it whenever a successful retrieval or modification returns a newer resource version. Keep it tied to the correct calendar and event.
An etag is not the appointment’s business status. It cannot tell the integration whether the patient confirmed, attended, cancelled, or rescheduled. It only identifies the version of the Google resource. Keep booking state in its defined system and map calendar changes through an explicit reconciliation rule.
Do not copy event descriptions, attendee details, patient names, or clinical notes into conflict logs. A useful record can contain an approved calendar alias, event identifier or fingerprint, old and current version fingerprints, operation type, fields in conflict, response status, and resolution outcome.
Calendar coverage matters as much as version control. Secondary Google calendars in Jane online booking explains why a correct write to one calendar does not prove that every calendar affecting availability is covered.
When is conditional retrieval useful?
Google also supports conditional retrieval with If-None-Match. A client sends the etag from its current copy. If the resource changed, Google returns the new version. If it did not change, Google returns HTTP 304 Not Modified.
Conditional retrieval can reduce unnecessary data transfer, but it does not replace If-Match at the write boundary. A client may confirm that an event is current and still lose a race before its later update. The write itself needs the version condition.
Google notes special cases in which an etag does not change, including certain read-only changes on a calendarList entry. Do not generalize event-update behavior to every Calendar resource without checking its contract.
When the integration only needs occupancy rather than event fields, review Google Calendar FreeBusy errors and provider slots. Fetching a detailed event and guarding its write solve a different problem from deciding whether a time is busy.
How can the conflict path be tested?
Use a synthetic event in an authorized test calendar. Retrieve the event and save version A. Modify it separately to obtain version B. Then attempt an update with version A in If-Match. The acceptance condition is an HTTP 412 response and preservation of the version B change.
Next, fetch version B, apply only the intended nonconflicting change, send its etag, and confirm the request succeeds with a new etag. Repeat the test for a conditional delete. Keep every title, attendee, description, and identifier synthetic.
Test a true conflict in which staff and the integration both change the appointment time. The application should stop or invoke its approved resolution rule. It should not silently choose whichever write happened last.
Finally, interrupt the job after a 412 and before resolution. On restart, it should fetch the current event again rather than reuse the stale payload. This proves that the queue stores intent and version evidence instead of blindly replaying an obsolete resource.
What should operations monitor?
Track conditional-update attempts, 412 rate, repeated conflicts for one event, resolution time, retry count, and operations sent without If-Match. These thresholds are operational choices. Google does not prescribe clinic-specific alert limits in the resource-version guide.
A rise in 412 responses may mean staff and automation are editing the same fields or that queue latency is making versions stale. Inspect the operation type and conflict fields before changing the policy. Removing the condition would reduce the visible error while increasing the chance of lost edits.
Keep acquisition reporting outside conflict resolution. A calendar edit does not establish a new booking source. The guide to appointment source versus marketing source shows which evidence should remain stable after operational changes.
Frequently asked questions
What does Google Calendar HTTP 412 mean here?
It means the etag in If-Match did not match the current resource version. The event changed after the client retrieved the older copy.
Should the integration retry without If-Match?
No. Fetch the latest event, resolve the conflict, and retry with the current version. Removing the condition can overwrite the newer edit that produced the 412.
Can If-Match protect a newly inserted event?
No. Google says conditional modification is not supported for insert operations. Creation needs its own identifier and retry contract.
Does an etag show whether an appointment was confirmed?
No. An etag identifies a Google resource version. Confirmation, cancellation, attendance, and booking ownership require separate business-state evidence.
A clinic cannot send an ordinary free-form WhatsApp reply whenever it chooses. Under the WhatsApp Business Messaging Policy, a business may reply without a Message Template only within 24 hours of the person’s last message. Outside that customer service window, the Business Platform requires an approved Message Template.
That platform rule answers which WhatsApp message format is available. It does not decide whether a clinic may send the reminder under HIPAA, another privacy law, a communications rule, its contract, or its own policy. Treat platform permission and legal permission as separate gates. A message should pass both before it enters the delivery queue.
What does the WhatsApp 24-hour rule control?
The policy controls how a business can send a message through the WhatsApp Business Platform. A clinic may reply without a Message Template when the reply falls within 24 hours of the person’s last message. Once that period has passed, only an approved Message Template can be used.
The clock is tied to the last message from the person, not the time of the appointment, the time the booking was created, or the time of the clinic’s previous outbound message. A reminder worker that checks only appointment time can therefore choose the wrong WhatsApp message type.
The policy also says businesses may initiate conversations only with approved Message Templates. A clinic should not treat a saved phone number as an open conversation. The person’s number, opt-in status, last inbound message time, and intended message type answer different questions.
Operational inference: calculate the available send path at execution time. A reminder approved for a free-form reply when it entered a queue may sit there until the 24-hour window has closed. Recheck the state immediately before delivery instead of trusting an earlier classification.
Does an approved template make the reminder legally permitted?
No. Approval means the template passed WhatsApp’s platform process for its designated purpose. It is not a legal opinion about the clinic’s use, its relationship with the person, or the information inserted into the template.
WhatsApp requires businesses to obtain necessary notices, permissions, and consents and to comply with applicable law. Its policy also warns against sending or requesting health-related information when applicable rules prohibit distribution to systems that do not meet heightened requirements. The policy does not declare that every clinic, vendor arrangement, template, or booking reminder is HIPAA compliant.
A clinic still needs its own documented review of the channel, vendor relationship, message purpose, recipients, data fields, retention, and escalation process. Where HIPAA applies, qualified privacy and legal reviewers should determine what agreements and safeguards are required. The WhatsApp policy cannot replace that work.
This separation also prevents a common reporting error. Message acceptance, delivery, or reading does not prove that the patient confirmed or attended. The article on preventing duplicate appointment reminders explains why each communication purpose needs one clear owner and a tested outcome path.
What state should a reminder workflow keep?
A reliable workflow needs enough state to make the send decision without storing a copy of the conversation in every downstream system. The minimum operational record usually includes an internal recipient reference, channel opt-in state, last inbound WhatsApp timestamp, template identifier when required, planned send time, delivery state, and opt-out state.
Operational inference: keep the last inbound timestamp separate from the appointment record. A reschedule changes the appointment time but does not, by itself, create a new user message. Likewise, a new inbound message can change the available WhatsApp reply path without changing the appointment.
The sender should evaluate the record in a fixed order:
Confirm that the person supplied the phone number and has the required opt-in.
Check for a later opt-out or request to stop messages.
Read the latest verified inbound WhatsApp timestamp.
Select a free-form reply only if the 24-hour condition still holds.
Otherwise select an approved template for the intended purpose.
Apply the clinic’s separate privacy and legal gate.
Send once and record the technical result without clinical content.
If the clinic has several reminder systems, do this check at the final sender, not only in an upstream CRM. A second tool may have newer consent or conversation state. Review appointment reminders versus intake reminders before combining separate messages into one automation.
How should opt-in and opt-out affect booking messages?
WhatsApp says a business may contact a person only when the person has provided the mobile number and given opt-in permission for later messages or calls. The business is responsible for how it obtains that permission and for the notices required by applicable law.
The policy also requires businesses to respect requests to block, discontinue, or opt out of communications, whether the request arrives on WhatsApp or elsewhere. A recent inbound message does not cancel an opt-out. The 24-hour window and opt-in are cumulative conditions, not alternatives.
Record what category of communication the person expected. WhatsApp’s best practices recommend that opt-in cover the categories the business will send and that opt-out instructions remain clear. Do not silently broaden a booking-reminder permission into promotional outreach.
Operational inference: make opt-out suppression authoritative at send time. If consent information comes from more than one system, define which record wins and how quickly a withdrawal reaches the sender. A delayed nightly copy is a poor control for a reminder due in an hour.
What should the message contain?
The 24-hour rule does not authorize every field that a template can technically accept. Keep platform formatting separate from content approval. A template should use only the fields reviewed for that communication and should avoid turning a routine reminder into a clinical disclosure.
WhatsApp expressly prohibits asking people to share full payment-card numbers, financial account numbers, full personal identification numbers, or other sensitive identifiers. Its policy also places responsibility for privacy notices, permissions, and lawful handling on the business.
A practical booking reminder can often direct the person to an approved scheduling or patient portal rather than copying detailed intake information into chat. That is an operational design choice, not a statement that a link alone satisfies HIPAA or another rule. Review the actual landing page, authentication, URL parameters, vendor access, and retention.
Keep the original booking source separate from the latest messaging channel. A person replying on WhatsApp does not mean WhatsApp acquired the booking. See appointment source versus marketing source for the reporting boundary.
How should a clinic test the 24-hour branch?
Use synthetic contacts in an authorized test setup. Do not test with real names, phone numbers, appointment reasons, medical notes, insurance data, or other patient information. The goal is to prove the state machine, not to reproduce a real visit.
Test at least four paths: an opted-in contact inside the window, an opted-in contact outside the window, a contact with no valid opt-in, and a contact who opted out after an earlier permission. Confirm that the first path can use the approved free-form workflow and the second is routed to the approved template path.
Then delay a queued job until it crosses the window. The sender should reclassify it before delivery. Test a template that is unavailable or no longer approved and confirm the workflow stops or moves to a reviewed exception path rather than substituting an unapproved message.
Automation within the 24-hour window still needs an escalation route. WhatsApp lists options such as transfer to a human agent, phone, email, web support, an in-person location, or a support form. Test the route the clinic actually offers and make it visible to the person.
What evidence should operations retain?
Retain evidence that explains the decision without retaining unnecessary conversation content: internal message reference, policy path selected, opt-in state, opt-out check, last inbound timestamp, template identifier, send time, delivery result, and escalation outcome. Limit access and retention under the clinic’s approved policy.
Do not label a reminder successful merely because the API accepted it. Delivery and read states, when available, are communication states. Booking confirmation and attendance belong to the scheduling system’s workflow and require their own status evidence.
Operational inference: alert on blocked sends by reason. Separate expired-window routing, missing template, missing opt-in, opt-out suppression, technical failure, and privacy review hold. This helps staff correct the right condition without opening chat transcripts or appointment details.
When marketing measurement is involved, keep the message record away from advertising payloads unless the use has been specifically approved. A neutral internal event can support operations without exporting booking or health detail.
Frequently asked questions
Can the clinic send a normal WhatsApp reply 25 hours after the patient’s last message?
Not under the free-form reply rule. Outside the 24-hour customer service window, the WhatsApp Business Platform requires an approved Message Template.
Does a template approval prove HIPAA compliance?
No. Template approval is a WhatsApp platform decision. The clinic must assess HIPAA and every other applicable legal, contractual, privacy, and security requirement separately.
Is a phone number enough to send booking reminders?
No. WhatsApp’s policy requires both the person’s mobile number and opt-in permission for later messages or calls. The clinic must also honor later opt-outs.
Does a new appointment restart the 24-hour window?
The policy ties the window to the person’s last WhatsApp message, not to appointment creation or rescheduling. A booking event alone should not be treated as a new inbound message.
NexHealth can disable a webhook endpoint after it continues returning errors for 48 hours. Its webhook documentation says non-2xx responses trigger retries. If those errors continue across that period, NexHealth sets the endpoint’s active state to false and stops sending webhooks to it.
Repair the receiver before reactivation. Confirm HTTPS delivery, request validation, durable acknowledgement, and the endpoint’s response path. Then inspect the endpoint and its needed subscriptions, set the intended resource active through the documented update operation, and reconcile the affected business window independently. Reactivation does not by itself prove that events from the inactive period were replayed.
Why did NexHealth set the endpoint to inactive?
NexHealth’s Webhook Endpoints reference describes a fail-safe for receivers that keep returning errors. A response outside the 2xx range is treated as unsuccessful and retried. If the endpoint continues producing errors for 48 hours, NexHealth changes the endpoint’s active property to false and stops sending webhooks to it.
This is endpoint transport state, not a statement about whether the connected EHR is healthy. A NexHealth sync can be green while the webhook receiver is inactive. It can also be red while the endpoint itself still accepts deliveries. Monitor those boundaries separately.
The article on NexHealth sync-status webhook direction covers the read and write health signals, including the current documentation conflict for write events. Endpoint deactivation answers a different question: whether NexHealth will attempt to deliver subscribed webhook events to a registered URL.
Do not reactivate immediately to silence an alert. If the receiver still returns errors, the incident continues and the same protection can apply again. First identify why the endpoint could not acknowledge accepted requests.
Which responses count as errors?
The mapped NexHealth documentation defines success by the HTTP response class. A 2xx response is successful; a non-2xx response triggers retry behavior. That makes the response path a control boundary. The handler should not return success before it has completed the local step required to avoid losing the event.
The exact durable step belongs to the integration design. It may be a committed database record or an accepted message in a durable queue. NexHealth does not require one storage product in these sources. The important distinction is that an in-memory task is not durable merely because the endpoint returned 2xx.
At the same time, do not hold the HTTP request open while running every downstream workflow. A short receiver can validate the request, store the event safely, return the appropriate response, and let a worker perform the slower action. This is operational guidance based on the documented acknowledgement and retry boundary.
NexHealth’s behavior differs from the contract described in Zocdoc’s HTTP 500 webhook handling. Do not reuse one vendor’s retry assumptions for another vendor.
What should be inspected before reactivation?
Start with the current endpoint record. NexHealth provides an operation for listing webhook endpoints, including active-state filtering, and an update operation for changing an endpoint. Confirm that the URL, environment, secret configuration, and intended active state match the receiver that was repaired.
Then inspect the subscriptions attached to the endpoint. An active endpoint and an active subscription answer separate questions. The endpoint determines whether the destination can receive deliveries. The subscription determines which event stream is attached to that destination. The documented subscription update surface includes its own active state.
Do not assume that toggling one resource silently repairs the other. Record the endpoint identifier, subscription identifiers, environment, previous states, approved change, and verification result. Avoid patient payloads. NexHealth warns that webhook events may contain PHI, while this recovery record needs only technical configuration.
Repair the narrow cause before changing active. Confirm the public HTTPS endpoint resolves to the intended service, the route accepts the expected method, the receiver can validate the configured secret, and the durable acknowledgement path works when a dependency fails or recovers.
Keep the endpoint inactive while the failing route is under repair.
Test request validation with synthetic, non-patient content.
Prove that accepted events reach durable storage before acknowledgement.
Prove that a rejected request returns the intended non-2xx response.
Confirm workers process repeated test events idempotently.
Inspect endpoint and required subscription states.
Reactivate only the approved resources through the documented update operations.
Do not print a webhook secret or full request body during testing. Store secrets in the approved secret manager and use a technical event fingerprint for correlation. Patient names, contacts, reasons, notes, insurance details, and clinical text do not belong in general observability.
A healthy receiver also needs bounded downstream failure handling. If a worker cannot apply an accepted event, keep the event visible for retry or review. Returning 2xx transfers recovery responsibility to the local system.
Does reactivation replay the missing window?
The mapped endpoint pages explain retries, automatic deactivation, active-state inspection, and reactivation. They do not promise that changing active back to true replays every event that occurred while the endpoint was inactive. Treat replay as unproven unless NexHealth supplies a separate current contract for the event and account.
This does not mean that replay never occurs. It means the reactivation response is not sufficient evidence. Build a bounded reconciliation interval from the last trusted processed event through the point when live delivery is verified again. Compare current source state with local state through approved identifiers.
Do not blindly recreate every appointment or resend every message from that interval. An operation may have succeeded through another path, and unconditional replay can create duplicates. The guide to preventing duplicate appointment reminders shows one downstream effect of applying the same scheduling event twice.
Preserve the original appointment lineage during recovery. An event applied after reconciliation is not a new acquisition. Keep the original source and later technical recovery state in separate fields.
How can live delivery be verified after reactivation?
Use an approved non-production environment or a synthetic event that cannot affect a real patient. After reactivating the intended endpoint and subscription, generate one supported test condition, observe the request at the receiver, verify it passes authentication, and confirm the worker reaches the expected technical state.
A 2xx response proves only that the receiver acknowledged that request. Add evidence from durable receipt and downstream completion. Record the endpoint, subscription, event class, one-way fingerprint, receipt time, response class, processing result, and environment.
Also test repeated delivery. The receiver should recognize an already accepted event or make the resulting state idempotent. It should not create another appointment, notification, or conversion merely because the same technical event arrived again.
If availability is involved, verify it through the appropriate API rather than inferring it from webhook traffic. NexHealth availability with an apparently open EHR calendar covers working hours and appointment-type assignment. Webhook recovery does not repair those inputs.
What should monitoring alert on?
Monitor both delivery symptoms and configuration state. Alert on sustained non-2xx responses, endpoint state changing to inactive, an expected subscription becoming inactive, and absence of expected technical events during a period when the business flow is active. Silence alone is not enough without activity context.
Keep EHR sync health beside, but separate from, webhook endpoint health. A useful dashboard shows endpoint active state, required subscription states, recent response classes, durable processing outcomes, and current read and write sync status. One green indicator should not hide another failed boundary.
Resource identity matters as well. When reconciling availability, do not collapse two operatories into one because they share a time. The article on NexHealth operatory identity for the same available time explains that scheduling scope.
Close the incident only after the receiver is stable, intended resources are active, a controlled live delivery completes, and the bounded gap has been reconciled. The active flag is necessary evidence, but it is not the whole recovery proof.
Frequently Asked Questions
What makes NexHealth retry a webhook?
The mapped documentation says NexHealth retries when the endpoint returns a response outside the 2xx range. Repair the response path rather than assuming an error response will remain harmless.
When does NexHealth disable the endpoint?
If endpoint errors continue for 48 hours, NexHealth sets the endpoint’s active state to false and stops sending webhooks to that destination.
Does setting active to true replay missed events?
The mapped pages do not promise complete replay for the inactive window. Reactivate the repaired resources, verify new delivery, and reconcile the gap independently.
Should webhook payloads be copied into application logs?
No. NexHealth warns that webhooks may contain PHI. Log technical identifiers, validation outcomes, response classes, and processing state without copying patient or clinical content.
A Zocdoc visit reason can remain unbookable even when its ID appears in allowed_visit_reason_ids because excluded_visit_reason_ids takes precedence. If the same identifier appears in both fields, the exclusion wins. When both populated arrays contain the same complete set, the timeslot allows no visit reason and cannot be booked.
Fix the conflict in the slot eligibility data, not in the clinic’s EHR mapping or patient workflow. Retrieve the current Zocdoc identifier, compare both arrays, confirm the intended provider, location, and patient type, then publish a corrected complete provider-day. Do not remove an exclusion merely because its label looks familiar.
Why does the excluded list win?
Zocdoc’s Create Timeslots guide defines the relationship directly. allowed_visit_reason_ids limits which reasons may use a slot, while excluded_visit_reason_ids names reasons that may not use it. When an identifier appears in both, the excluded list supersedes the allowed list.
This is a precedence rule, not a merge conflict that the booking client may resolve. A reason in both arrays is not partly eligible, conditionally eligible, or eligible because the allow list was processed first. The final answer for that reason is excluded.
The rule also explains the most confusing failure case. Suppose a slot’s allowed list contains the same populated set as its excluded list. Every allowed candidate is then removed by the higher-priority exclusion. The slot has no eligible visit reason, so the patient cannot book it through that configuration.
Keep this boundary separate from mapping Zocdoc visit reasons to EHR appointment types. A correct local mapping cannot override a Zocdoc slot exclusion. Eligibility must pass before the integration selects any EHR destination.
What do null and empty arrays mean?
The two fields do not use emptiness in the same way as a populated list. Zocdoc documents a null or empty allowed_visit_reason_ids value as no allow-list restriction. It does not mean that zero reasons are allowed. A null or empty excluded_visit_reason_ids value means that no reason is excluded by that field.
Allowed field
Excluded field
Eligibility result
Null or empty
Null or empty
No restriction from either list
Populated
Null or empty
Only listed allowed reasons qualify
Null or empty
Populated
Reasons qualify except those excluded
Populated
Populated
Apply the allowed set, then remove every excluded reason
Do not normalize null or empty allowed values into an empty mathematical set without preserving this vendor meaning. That transformation can turn an unrestricted slot into an unbookable one. Likewise, do not delete the excluded field during serialization merely because the allowed field exists.
How should the effective reason set be calculated?
Calculate eligibility with one explicit rule. Begin with the reasons permitted by the allowed field. If that field is null or empty, begin with the applicable Zocdoc reasons for the scheduling context. Remove every reason named in the excluded field. The remainder is the effective bookable set for that slot.
This description does not authorize the integration to invent the universe of applicable reasons. Use Zocdoc reference data and the approved provider context. The Reference Data guide supplies Zocdoc-specific IDs, and the glossary defines how allowed and excluded reasons behave. Local labels are reviewer aids, not substitutes for identifiers.
A compact diagnostic record can preserve the slot’s technical identifier, provider, location, patient type, allowed IDs, excluded IDs, and computed result. Keep patient names, contact details, visit notes, and clinical text out of this record. The question is slot configuration, not patient history.
Once eligibility succeeds, the local appointment-type mapping is a separate gate. The article on appointment source versus marketing source explains another separation worth preserving: neither an acquisition field nor a campaign label should change which visit reason a slot accepts.
Why can a valid ID still fail?
A valid Zocdoc ID proves that the referenced visit reason exists in the vendor’s reference data. It does not prove that every provider, location, patient type, or timeslot accepts that reason. Validity and eligibility answer different questions.
Start by retrieving or confirming the identifier through the current reference-data surface. Then inspect the exact timeslot object involved in the failed booking. Compare the reason against both eligibility arrays. A reason may be valid globally yet absent from a populated allowed list, present in the excluded list, or both allowed and excluded.
Do not diagnose this by comparing display names alone. Two labels can look similar while representing different IDs or scheduling scopes. Conversely, a label may change while the integration contract still depends on the ID. Preserve both for review, but make the technical decision with the documented identifier.
If the reason is eligible for the slot but booking still fails, move to the next boundary. Check the clinic-owned mapping, destination availability, and request contract. The guide to availability that looks open in an EHR but returns no slots shows why visible calendar space is not enough to prove end-to-end eligibility.
How should a conflicting slot be corrected?
Correct the source rule that produced the conflict. First decide whether the visit reason should be admitted for the exact provider, location, date, time, and patient type. If it should be admitted, remove the unintended exclusion. If it should not, remove the misleading allowance or leave the exclusion as the governing rule.
Confirm the current visit-reason ID through Zocdoc reference data.
Locate the exact provider-day snapshot that generated the slot.
Compare the reason against both arrays before serialization.
Resolve the clinic rule that created the contradiction.
Recompute every slot for that provider and date.
Validate that each slot has the intended effective reason set.
Publish one complete corrected provider-day.
The final step matters because the Zocdoc timeslot operation replaces availability for one provider and date. The article on Zocdoc provider-day replacement behavior explains why sending only the corrected slot can remove valid slots omitted from the request.
Do not treat removal from an exclusion list as harmless cleanup. It changes what patients may book. Require the same operational approval used for provider availability and appointment-type rules, then record the rule version without copying patient data.
What checks should run before publication?
Run a deterministic eligibility check on every generated slot. Confirm that all populated IDs exist in current reference data, detect duplicates, compute the final set with exclusion precedence, and reject a slot whose final set is empty when the clinic intended it to be bookable.
The check should distinguish an intentional restriction from an accidental contradiction. A slot may correctly exclude one reason while admitting others. The failure worth blocking is a mismatch between the approved scheduling rule and the computed output, not the mere presence of an excluded list.
Test the main combinations with synthetic configuration. Cover unrestricted fields, allowed-only, excluded-only, partial overlap, and complete overlap. For partial overlap, verify that only the overlapping reason is removed. For complete overlap, verify that the slot is recognized as having no eligible reason.
Also test the corrected full-day publication. Confirm that unrelated slots remain present and the target reason becomes bookable only where approved. If appointment actions are part of the test, use synthetic records and follow the documented boundary for Zocdoc cancellation and reschedule webhooks.
How should this failure be monitored?
Monitor the effective eligibility result, not only the presence of values in the two source fields. An alert that says “reason appears in allowed list” misses the precedence rule. A useful signal says that a provider-day contains a slot whose computed set is empty or differs from the approved rule.
Record technical scope, list hashes or identifiers, computed count, validation result, rule version, and publication result. Do not place full appointment payloads or patient data in general logs. When the same configuration repeatedly returns, trace the upstream rule generator instead of patching each serialized payload.
After correction, verify the current slot behavior. A successful request proves acceptance of the submitted payload, not that the business rule was correct. Keep the operational verification separate from later appointment status updates such as the Zocdoc no-show reporting window.
Frequently Asked Questions
Does allowed_visit_reason_ids override an exclusion?
No. Zocdoc documents that the excluded list takes precedence. A visit-reason ID present in both arrays remains excluded from that timeslot.
Does an empty allowed_visit_reason_ids array block every reason?
No. The documented behavior treats a null or empty allowed list as no allow-list restriction. Apply any populated excluded list separately.
What happens when both arrays contain the same reasons?
Every candidate admitted by the allowed list is removed by the excluded list. The slot then has no eligible visit reason and is unbookable.
Can an EHR appointment-type mapping make the reason bookable?
No. The local mapping runs after slot eligibility. It can select an approved destination for an eligible reason, but it cannot override Zocdoc’s exclusion rule.
A clinic’s Google Business Profile verification video is rejected when it does not show the required evidence in one acceptable recording: the real location, the business’s permanent presence, and the recorder’s authority to manage it. Review the stated issue, clear the clinic of patients and private material, then record a new live video.
The video must be continuous, unique, at least 30 seconds long, and recorded through the Business Profile on a mobile device. Never film patients, other people’s faces, charts, screens, IDs, forms, mail, or sensitive documents. Google permits non-sensitive business documents as management evidence in applicable flows, but a clinic can usually prove control through safe physical access with less privacy risk.
Why was the clinic’s verification video rejected?
Google lists practical rejection examples: the business name was not visible on the storefront, the nearby area was missing, or the recording did not prove authority to operate the business. A polished tour cannot compensate for one missing category. The reviewer needs connected evidence that matches the profile being verified.
Start with the notice under Review issues. Treat each listed problem as a required correction. Keep everything that was clear in the first attempt and add the missing evidence in the new recording. Do not edit the old file or upload a prerecorded replacement. Google requires a fresh live recording through the profile.
A video rejection does not mean the clinic should create another Business Profile. It also does not establish suspension, duplicate status, or ineligibility. Those are different states with different remedies. Verify the exact message before changing the profile’s name, category, or address.
If the profile’s appointment link has a separate problem, use the guide to why Google removed a clinic appointment link. Link review and business verification should remain separate investigations.
What must a storefront clinic show in the new recording?
A storefront clinic should connect three facts in one continuous route. First, show the real surroundings with a street sign, building number, nearby business, or recognizable place. Second, show the clinic’s name on permanent signage. Third, show that the recorder is authorized to manage the location through access that an ordinary visitor would not have.
The name on the permanent sign should match the Business Profile. A temporary paper taped to a door is weak evidence of a permanent presence. If the clinic shares a building, include enough exterior context to locate the correct suite without sweeping the camera across other people’s private activity.
For management proof, prefer a safe physical action. An authorized employee can unlock the clinic entrance or open a staff-only room after confirming that it is empty. Google also allows non-sensitive business documents in applicable cases. If one is needed, inspect every visible field first and exclude personal, clinical, financial, or confidential information.
Clinic structure matters before verification. A medical office may have a location profile and eligible practitioner profiles. Read who controls a Business Profile booking link to understand ownership boundaries, then confirm that the video and account belong to the same entity.
How can a clinic record safely without patients or documents?
Schedule the recording when the premises are closed to patients and visitors. Tell staff not to enter the route. Clear whiteboards, sign-in areas, delivery labels, wall schedules, patient materials, mail, and loose private paper from the camera’s view. Turn monitors off rather than trying to blur them later, since the video cannot be edited.
Walk the route before opening the recorder. Begin outside with location evidence, move to the permanent business sign, then demonstrate controlled access. Keep the camera aimed narrowly. Stop and restart the whole process if a person, private document, screen, or confidential conversation enters the frame.
Do not ask a patient to appear, even with permission. Do not use a patient chart or appointment list as proof that the clinic operates. The official requirement is proof of the business and the recorder’s management authority. Patient information adds no useful verification value.
The same restraint applies after verification. The article on safe clinic responses to Google reviews explains why public profile management should avoid confirming a person’s relationship with the practice.
Can the clinic choose a different verification method?
Not on demand. Google says it automatically determines the methods offered to a Business Profile, based on factors such as business type, public information, region, and business hours. The available options can include video, phone or text, email, live video call, or mail. Some profiles may need more than one method.
Use the options shown in the profile. If video is available and the first recording failed, select Review issues and follow the listed corrections. If another method is offered, the clinic can use that displayed route. Support cannot be treated as a shortcut for inventing an option that the profile does not offer.
Keep verification codes private. Google states that it will not ask the business to share a code. An agency or vendor should receive manager access after ownership is established, rather than controlling the clinic through a personal account or asking staff to forward codes.
Changing the business name, address, or category while troubleshooting can trigger more review or re-verification. Make only corrections that reflect the real clinic. Do not reshape the profile to chase a supposedly easier verification method.
How should the clinic respond to “Review issues”?
Read every reason before recording again. Translate each issue into a visible scene. If the business name was missing, plan a clear view of permanent signage. If the nearby area was absent, add the building number and surrounding context. If management proof was missing, plan a safe staff-only access action.
Then create a short shot list without filming it. The recording itself must remain one unedited sequence. Confirm mobile location, camera, and microphone permissions before starting. Use a stable network and stay inside the Business Profile workflow so the recording can upload from the device.
After recording, review the preview for accidental private material. If anything appears, discard it and record again. Google allows a new attempt when the requirements were not met. A failed first video does not justify accepting privacy exposure in the second.
Google says review can take up to five business days. Wait for the stated result rather than making repeated profile edits during that period. If the second attempt fails, compare the new notice with the shot list and contact support only after the available verification route has been followed carefully.
What does verification prove, and what remains unproven?
Verification gives the clinic ownership of the Business Profile and supports accurate management of its public information. It does not prove that appointment links work, that a scheduling vendor writes to the correct calendar, or that calls and bookings came from a specific marketing source.
After approval, inspect the public profile in Search and Maps. Confirm name, location, phone, hours, website, and appointment action. If a former vendor still controls a link, follow the process for removing a third-party booking link rather than deleting every booking option.
Verification also does not authorize the clinic to send health-related details to analytics or advertising products. Keep URLs, event names, support screenshots, and campaign reports generic. Public profile ownership and data-use permission are separate decisions.
Do not report the video as acquisition proof. A successful verification tells the team that Google accepted the evidence of business control. It does not quantify visibility, calls, directions, appointments, new patients, or revenue.
How can the clinic avoid another verification failure?
Keep the Business Profile under a clinic-controlled account and assign named managers. Record the exact public name, address, category, permanent signage, and ownership contacts in an internal control note. Do not store verification videos in general marketing folders or forward them through informal channels.
Review access when staff, agencies, or vendors change. Re-verification can follow changes to business information, so plan evidence before editing high-impact fields. The physical sign, public profile, website, and booking destination should describe the same clinic entity.
Use a reusable privacy checklist for any future recording: empty premises, clear route, screens off, no people, no sensitive documents, and no private audio. If non-sensitive business evidence is needed, approve it before recording and expose only what the verification requires. The checklist can be retained. The video itself should be deleted through the profile when it is no longer needed and Google offers that control.
If the clinic has multiple locations, keep one evidence set per eligible profile. Do not reuse another branch’s exterior, sign, or staff access. Each verification should establish the location and management authority of the profile in front of the reviewer.
Frequently asked questions
Can the clinic upload a prerecorded or edited verification video?
No. Google requires a live, unique, continuous recording made and uploaded from a mobile device through the Business Profile. If the route fails or private material appears, discard it and make a new complete recording.
Should a patient appear to prove the clinic is operating?
No. Keep patients and all other faces out of the video. Show the location, permanent signage, and safe staff-only control instead. A patient adds privacy risk and is not needed to prove management.
Can the clinic film a license, invoice, or schedule?
A patient schedule should never be filmed. Google can accept non-sensitive business documents such as a license or invoice as management evidence in applicable cases. For a clinic, prefer physical access when it proves control; if a document is necessary, confirm it contains no personal, clinical, financial, or confidential information.
Does video approval guarantee the appointment button will work?
No. Verification establishes control of the profile. The clinic still needs to test the public link, correct location, booking action, schedule write-back, privacy controls, and marketing measurement separately.
