Webhooks send information from doxy.me to another system when certain events happen during a patient visit.
Webhooks can send events when:
A patient checks into a Waiting Room
A provider starts a call
A call ends
A patient leaves the Waiting Room
Available on paid plans ⭐
How to set up or manage webhooks
Use your clinic's webhook management page to set up and manage your webhook configuration.
Go to Settings and select the Webhooks page under Clinic
Use the Add webhook button in the upper right corner to create a new webhook
Enter a name that describes the webhook’s purpose (e.g. EHR notifications)
Enter the webhook URL
Select events to send via the webhook
Call start
Call end
Check-in
Patient left
Check the box to confirm that you or your organization own the endpoint supplied earlier
Or, review existing webhooks in the table on the page.
Fields of existing webhooks include:Name
URL
Event
Signing secret
Status
See our webhook documentation below for event formats, fields, security requirements, and implementation examples.
Available webhook events
Meeting started: Sent when a provider starts a call with a patient
Meeting ended: Sent when a call ends
For Group Calls, this event may be sent more than once as participants leave the call.
Check-in: Sent when a patient enters a provider's Waiting Room
Patient left: Sent when a patient leaves the Waiting Room before being seen
This event may not be delivered if the patient's connection drops or another technical issue prevents delivery.
Webhook security
Every webhook request includes a secret key associated with your account.
Your receiving system should validate this secret key before processing the webhook request.
For production use:
Only accept webhook requests over HTTPS
Store your secret key securely and outside of your source code
Treat the secret key like any other credential
If your secret key needs to be replaced, contact our support team. After the key is changed, you’ll also need to update it in your receiving system.
Webhook delivery
Doxy.me currently sends each webhook event once. Failed deliveries are not automatically retried or queued.
If your endpoint is unavailable or returns an error, that event may be lost. Make sure your receiving endpoint responds quickly and reliably.
Troubleshooting webhooks
If your webhook is not working as expected:
Confirm that your receiving endpoint is available
Confirm that your system is receiving webhook requests
Confirm that your endpoint is returning a successful 2xx response
Confirm that your system is validating the correct secret key
Check whether your integration uses a provider's room slug or room link
If your clinic recently migrated, confirm that your system is using the provider's current doxy.me room information
If you need help, contact our support team.
Technical webhook documentation
For webhook payloads, event formats, security requirements, and implementation examples, see our webhook documentation by expanding the section below.
Technical information (click the ▶︎ to view)
Technical information (click the ▶︎ to view)
Overview
Doxy.me provides four webhook events that clients can subscribe to: ‘check-in,' ‘call start,’ 'call end', and 'patient left.’ These events help clients to track patient interactions within the platform.
Webhook Events
Check-in: Triggered when a patient enters the waiting room.
Call Start: Triggered when a provider starts a call with a patient.
Call End: Triggered when a patient or provider ends the call. This event may be called multiple times. If there are several patients on the call, it will be called after each patient leaves the call.
Patient Left: Triggered when a patient leaves a waiting room. This event may be called multiple times. The event may be missing if the patient has connection issues or other technical issues.
Webhook Requests
Webhook requests contain the following data:
Check-in Event:
eventType : “CheckIn”.
eventId : Unique identifier of event.
name : Checked in patient's name.
roomSlug : The slug of the room where the patient checked in.
roomLink : URL of the room where the patient checked in.
checkinTime : The time when the patient checked in to the room.
pid : Patient ID provided in the ?pid= query parameter when the patient checked into the waiting room. May be absent if patient didn’t have it during check-in. Can be used to link patients to internal EHR.
Start Call Event:
eventType : “CallStart”.
eventId : Unique identifier of event.
id : Call identifier.
startTime : Date and time when the call started.
endTime : Always null in this event.
durationSeconds : Always null in this event.
providerDisplayName : Display name of the provider on the call.
providerFirstName : Providers first name.
providerLastName : Providers last name.
providerEmail : Providers email
roomSlug : The slug of the room where the call started.
pidList : List of patient IDs on the call. May be empty if patient didn’t have it during check in.
End Call Event:
eventType : “CallEnd”.
eventId : Unique identifier of event.
id : Call identifier.
startTime : Date and time when the call started.
endTime : Date and time when the call ended.
durationSeconds : Duration of the call in seconds.
providerDisplayName : Display name of the provider on the call.
providerFirstName : Providers first name.
providerLastName : Providers last name.
providerEmail : Providers email
roomSlug : The slug of the room where the call started.
pidList : List of patient IDs on the call. May contain several PIDs if multiple patients were on the call.
Patient Left Event:
eventType : “PatientLeft”.
eventId : Unique identifier of event.
name : Checked in patient's name.
pid : Patient id.
roomSlug : The slug of the room patient left.
Response
The API does not expect a response body from the client, but a 20* HTTP status code should be returned to acknowledge successful receipt of the webhook event.
Security
To ensure the request is originating from Doxy.me, validate the 'secret-key' header that is included in each webhook request. This 'secret key' is a static string uniquely generated for each clinic.
To illustrate, here's a simple code snippet showcasing how you can authenticate the request:
1 if (req.headers['secret-key'] !== ENV.DOXYME_SECRET_KEY) {
2 return res.status(403).send('Forbidden');
3 }
Error Handling and Retries
The webhook events are sent only once, and there's no built-in retry mechanism in case of delivery failures. In case of an error on the client side, no specific error messages are expected by the API.
If there are additional queries or need for further assistance, please feel free to contact our support team.
Testing locally / dev envs
To test integration locally you may use examples below:
Check-in Event
curl --location 'http://localhost:8080/doxy-me/webhook/check-in' \
--header 'secret-key: your-secret-key' \
--header 'Content-Type: application/json' \
--request POST \
--data '{
"eventType": "CheckIn",
"eventId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Peter Parker",
"roomSlug": "strange",
"roomLink": "https://example.doxy.me/strange",
"checkinTime": "2023-06-22T09:30:00.000Z",
"pid": "amazing1963"
}'
Start Call Event
curl --location 'http://localhost:8080/doxy-me/webhook/call-start' \
--header 'secret-key: your-secret-key' \
--header 'Content-Type: application/json' \
--request POST \
--data '{
"eventType": "CallStart",
"eventId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"id": "27f17da0-11b3-11ee-b2b6-e90ed8c43cc7",
"startTime": "2023-06-22T10:00:00.000Z",
"endTime": null,
"durationSeconds": null,
"roomSlug": "strange",
"providerDisplayName": "Stephen Strange",
"providerFirstName": "Stephen",
"providerLastName": "Strange",
"providerEmail": "strange@doxy.me",
"pidList": ["amazing1963"]
}'
End Call Event
curl --location 'http://localhost:8080/doxy-me/webhook/call-end' \
--header 'secret-key: your-secret-key' \
--header 'Content-Type: application/json' \
--request POST \
--data '{
"eventType": "CallEnd",
"eventId": "16fd2706-8baf-433b-82eb-8c7fada847da",
"id": "27f17da0-11b3-11ee-b2b6-e90ed8c43cc7",
"startTime": "2023-06-22T10:00:00.000Z",
"endTime": "2023-06-22T10:15:30.000Z",
"durationSeconds": 930,
"roomSlug": "strange",
"providerDisplayName": "Stephen Strange",
"providerFirstName": "Stephen",
"providerLastName": "Strange",
"providerEmail": "strange@doxy.me",
"pidList": ["amazing1963"]
}'
Patient Left Event
curl --location 'http://localhost:8080/doxy-me/webhook/patient-left' \
--header 'secret-key: your-secret-key' \
--header 'Content-Type: application/json' \
--request POST \
--data '{
"eventType": "PatientLeft",
"eventId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
"roomSlug": "strange",
"name": "Peter Parker",
"pid": "amazing1963"
}'
Moving from the legacy platform
If your clinic already uses webhooks on the legacy doxy.me platform, your webhook configuration will be migrated when your clinic moves to the doxy.me platform.
We recommend testing your webhook integration after your migration.
After migration, you’ll need to make sure your webhook integration accepts the updated roomSlug format.
On the legacy platform, a provider room might send:
roomSlug: roomname
On the doxy.me platform, the same room will send:
roomSlug: clinicname/roomname
If your integration uses roomSlug to identify providers, route information, or trigger workflows, update it to accept the new clinic/provider format.
We recommend testing your webhook integration after migration to confirm that events are being processed as expected.
How to check your webhooks after migration
After your clinic moves off of the legacy platform:
Complete a test patient visit
Confirm that your system receives the expected webhook events
Check any workflows that use a provider's room slug or room link
Update those workflows if they still reference room information from the legacy platform
Webhook migration FAQs
Will my existing webhooks move with my clinic?
Yes. Your existing webhook configuration will be migrated when your clinic moves from the legacy platform. We still recommend testing your integration after migration.
Why did my webhook integration stop working after migration?
Provider room information uses a different format on the doxy.me platform.
If another system relies on a provider's previous room slug or room link, that workflow may need to be updated even though the webhook itself was migrated.
Questions? Please contact our support team