Which Zocdoc Cancellation and Reschedule Changes Trigger a Patient-Booking Webhook?

Zocdoc’s patient-booking webhooks do not represent every cancellation or reschedule path. In that use case, webhook notifications are sent only for provider-initiated appointment changes. When a developer or patient initiates the action through the API flow, Zocdoc tells the developer to update internal systems from the API response and not wait for a webhook.

Two other checks matter. A reschedule request is accepted only from documented appointment states. The credential used for the original booking controls who may later view or modify it. Keep the API response and any provider-originated webhook attached to the same appointment state record.

Which appointment changes produce a patient-booking webhook?

Zocdoc says its webhooks cover changes to appointment statuses for appointments booked through /v1/appointments/, including cancellations and reschedules. It then narrows the patient-booking use case: webhook notifications are sent only for provider-initiated appointment changes.

For developer- or patient-initiated actions, the instruction is different. Update the internal system from the API response and do not wait for a webhook. A booking integration that waits for every cancellation to return through the webhook channel can leave its own record stale even though the initiating API request already completed.

This is an initiator boundary, not a statement that Zocdoc has no cancellation webhooks. Identify who initiated the change and which flow handled it. Keep that evidence with the appointment state, not in marketing attribution. The article on booking systems versus CRM ownership explains why operational truth should not be reconstructed from downstream marketing records.

What should happen after a developer-initiated change?

When the developer or patient initiates the cancellation or reschedule, use the response from that API operation to update the internal record. Do not create a pending state whose only exit depends on a webhook that the documented patient-booking flow does not promise.

Operational inference: store the action identifier, initiator class, request time, returned appointment data or outcome, and previous local state. Apply the response through an idempotent state transition. The source directs the integration to use the API response; it does not prescribe database columns, queue design, or the exact names of local states.

If the response is ambiguous or the request fails, do not guess that the appointment changed. Re-read the appointment through an authorized path or send the case to reconciliation. Keep availability publication separate until the booking state is known. For the related upstream contract, see how Zocdoc timeslot updates replace a provider day.

What should happen after a provider-initiated change?

A provider-originated cancellation or reschedule in the patient-booking use case is the path for which Zocdoc documents webhook notification. The webhook is an external event, so the receiver must authenticate it, identify the appointment, and apply the status change without assuming delivery occurs exactly once.

Zocdoc supports HTTPS for appointment status webhooks, with HTTP allowed only for sandbox testing. Each webhook request is signed with a shared key. The guide tells clients to verify the signature so they can confirm origin and detect tampering. It also uses a webhook timestamp and recommends checking that it is within a few minutes, with five minutes shown as the default.

Operational inference: acknowledge only after the event has reached durable processing, then make the state transition idempotent. The separate guide on booking webhook idempotency and audit evidence covers that generic implementation problem. Zocdoc’s source establishes the trigger, signature, and retry contract.

Which states can be rescheduled?

Zocdoc’s Appointment Actions guide permits a time change and reschedule request when the appointment is in pending_booking, confirmed, pending_reschedule, or rescheduled. The operation uses POST /v1/appointments/reschedule with the appointment_id and new start_time.

Do not send the operation from an unlisted state merely because the local interface offers an edit button. Validate the current Zocdoc state first. If local state differs, reconcile before retrying. The source lists the states accepted for this action, but it does not authorize an integration to manufacture one locally.

Visit-reason and EHR type mapping is another boundary. A new time does not repair a mismatched clinical scheduling code. Use the documented method for mapping Zocdoc visit reasons to EHR appointment types and validate the rescheduled appointment against the same mapping.

How does cancellation differ from rescheduling?

Cancellation uses POST /v1/appointments/cancel. The documented example sends an appointment_id, a free-text cancellation_reason, and a cancellation_reason_type. Rescheduling uses its own endpoint and supplies a new start time. They are separate actions rather than two labels for the same update.

Keep the local transition and audit record distinct. A cancellation should not silently reopen a slot unless the scheduling source and availability contract establish that result. A reschedule involves the old time and the requested new time, but the cited sources do not define a clinic’s inventory reconciliation algorithm.

Operational inference: reconcile both the appointment and affected availability after the API result or provider webhook is accepted. Do not copy cancellation text into analytics, Ads, or general logs. A reason may contain sensitive context. Store only what the approved booking workflow needs.

How does the original credential affect modification access?

Zocdoc documents the same credential boundary for cancellation and rescheduling. If an appointment was booked with a Zocdoc user credential, only that user can view or modify the appointment. If it was booked with a machine-to-machine credential, any of the developer’s machine-to-machine credentials can view and modify it.

A valid access token is therefore not enough by itself. The integration must know which credential class created the booking and select an authorized credential for the later action. A 401 or 403 should not be translated into an unsupported state change or a second appointment.

Operational inference: retain non-secret provenance that identifies the booking’s credential class and accountable principal. Never store an access token in the appointment audit record. If credential ownership cannot be established, stop the mutation and reconcile through an approved support path.

What retry behavior can surprise a webhook receiver?

Zocdoc says it retries webhook events with exponential backoff for up to 48 hours after the first attempt. Retries occur when a connection cannot be established, when no response arrives within five seconds, or when the connection ends before a response. Zocdoc does not retry based on the status code returned by the webhook endpoint.

A quick HTTP response does not prove durable processing. Returning an error status does not itself request another delivery under the documented rule. Taking longer than five seconds can create a retry even when the original handler continues working. The receiver must tolerate repeated delivery and avoid applying one provider change twice.

The payload signature uses a timestamp and JSON payload, and Zocdoc notes that the schema may change. Validate required fields while allowing compatible additions. Do not disable signature checking to accommodate a parser failure.

What end-to-end test proves the initiator boundary?

Use sandbox appointments and synthetic people only. Book one appointment with the credential class under test. Record its current Zocdoc state. Exercise a developer-initiated cancellation or reschedule, then confirm that the internal system updates from the API response without waiting for a webhook.

Next, use the supported sandbox path for a provider-initiated change and verify the signed webhook. Check that the receiver validates the timestamp and signature, responds within five seconds, and applies a repeated event only once. Test user-credential and machine-to-machine bookings separately because their later modification rights differ.

Pass only when the same final state is reached through the correct evidence path for each initiator. Do not use a webhook absence as proof that an API action failed. Do not use an API success from one credential class as proof that another credential can modify the booking.

Frequently asked questions

Will every Zocdoc cancellation send a webhook?

No. In the patient-booking use case, Zocdoc says webhook notifications are sent only for provider-initiated appointment changes. Developer- or patient-initiated actions should update internal state from the API response.

Which appointment states can the reschedule endpoint modify?

The documented states are pending_booking, confirmed, pending_reschedule, and rescheduled. Reconcile an appointment in any other state before attempting the operation.

Can any valid Zocdoc token cancel a user-booked appointment?

No. If the appointment was booked with a Zocdoc user credential, only that user can view or modify it. Machine-to-machine bookings follow the separate developer credential boundary.

Does returning HTTP 500 make Zocdoc retry a webhook?

Not under the documented retry rule. Zocdoc says retries are based on connection failure, no response within five seconds, or a severed connection, not the returned status code.

References

• Zocdoc for Developers, “Webhooks,” reviewed August 16, 2026, https://api-docs.zocdoc.com/guides/webhooks.
• Zocdoc for Developers, “Appointment Actions,” reviewed August 16, 2026, https://api-docs.zocdoc.com/guides/scheduling/appointment-actions.