{ "openapi": "3.0.3", "info": { "title": "Webhooks", "version": "3.0", "contact": { "email": "admin@vsee.com" }, "description": "Webhook event documentation for VSee Clinic API" }, "servers": [ { "url": "https://api.vseepreview.com/api_v3", "description": "Staging" } ], "x-readme": { "explorer-enabled": false, "proxy-enabled": false, "samples-languages": [ "curl", "python", "javascript", "java" ] }, "tags": [ { "name": "Webhooks", "description": "Webhook events and payloads" } ], "paths": { "/webhooks/events": { "post": { "tags": [ "Webhooks" ], "summary": "Webhook event", "description": "Webhook events are sent to your configured webhook URL. This documents the available event types and their payloads.", "operationId": "webhookEvent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/WebhookEventV1" }, { "$ref": "#/components/schemas/WebhookEventV2" } ] }, "examples": { "visitCreatedV1": { "value": { "version": "1.0", "id": "5c34979c-30dc-496c-8cd3-6eb9925862c1", "type": "visit.created", "created": 1546950556, "account_code": "xxx", "data": { "id": "28540", "member_id": "60610", "provider_id": null, "start": "1546950546", "end": "1546951446", "actual_start": "1546950546", "actual_end": "1546950555", "status": "scheduled", "completed_by": "60610" } } }, "visitEndedV1": { "value": { "version": "1.0", "id": "5c34979c-30dc-496c-8cd3-6eb9925862c1", "type": "visit.ended", "created": 1546950556, "account_code": "xxx", "data": { "id": "28540", "member_id": "60610", "provider_id": null, "start": "1546950546", "end": "1546951446", "actual_start": "1546950546", "actual_end": "1546950555", "status": "40", "completed_by": "60610" } } }, "visitCreatedV2": { "value": { "version": "2.0", "id": "5c34979c-30dc-496c-8cd3-6eb9925862c1", "type": "visit.created", "created": 1546950556, "clinic_code": "xxx", "data": { "id": "28540", "member_id": "60610", "provider_id": null, "start": 1546950546, "end": 1546951446, "actual_start": 1546950546, "actual_end": 1546950555, "status": "scheduled", "status_updated_by": "60610" } } }, "visitEndedV2": { "value": { "version": "2.0", "id": "5c34979c-30dc-496c-8cd3-6eb9925862c1", "type": "visit.ended", "created": 1546950556, "clinic_code": "xxx", "data": { "id": "28540", "member_id": "60610", "provider_id": null, "start": 1546950546, "end": 1546951446, "actual_start": 1546950546, "actual_end": 1546950555, "status": "cancelled", "status_updated_by": "60610" } } }, "visitNoteSigned": { "value": { "version": "2.0", "id": "5c34979c-30dc-496c-8cd3-6eb9925862c1", "type": "visit.note.signed_and_sent", "created": 1546950556, "clinic_code": "xxx", "data": { "id": "28540", "member_id": "60610", "provider_id": null, "start": 1546950546, "end": 1546951446, "actual_start": 1546950546, "actual_end": 1546950555, "status": "completed", "status_updated_by": "60610", "note": { "id": 123, "status": "signed" } } } }, "visitInvoiceProcessed": { "value": { "version": "2.0", "id": "5c34979c-30dc-496c-8cd3-6eb9925862c1", "type": "visit.invoice.processed", "created": 1546950556, "clinic_code": "xxx", "data": { "id": "28540", "member_id": "60610", "provider_id": null, "start": 1546950546, "end": 1546951446, "actual_start": 1546950546, "actual_end": 1546950555, "status": "completed", "status_updated_by": "60610", "invoice": { "id": "132", "status": "pending", "amount_due": 2500, "amount_paid": 1500, "currency": "USD" } } } }, "userCreated": { "value": { "version": "1.0", "id": "5c34979c-30dc-496c-8cd3-6eb9925862c1", "type": "user.created", "created": 1546950556, "account_code": "xxx", "data": { "user_id": "60610", "email": "patient@example.com", "first_name": "John", "last_name": "Doe" } } }, "visitMessageCreated": { "summary": "visit.message.created — new message on an eConsult visit (either direction)", "description": "Fires for every new message on the visit. The payload is a thin pointer: it deliberately carries no message content or PHI — fetch the thread with GET /api/visits/{visit_id}/messages. Filter on data.actor_type if you only want provider replies. Deliveries are retried up to 5 times, ~60s apart; de-duplicate by data.message_id and respond 2xx within 30s.", "value": { "id": "6a47ea02-4809-4af6-b8f6-c56bc2bd2adb", "type": "visit.message.created", "created": 1786755119, "account_code": "aubrey", "version": "1.0", "data": { "visit_id": "1000021648", "message_id": "83c3b3d7-346c-4ac9-8276-f96ac8356e25", "actor_type": "provider", "ts": 1786755119 } } } } } } }, "responses": { "200": { "description": "Webhook received successfully" } }, "x-auth-type": "admin-token", "parameters": [ { "name": "X-ApiToken", "in": "header", "description": "API token", "required": true, "schema": { "type": "string" }, "example": "your_api_token" }, { "name": "X-AccountCode", "in": "header", "description": "Account code", "required": true, "schema": { "type": "string" }, "example": "vclinic" } ] } } }, "components": { "schemas": { "WebhookEventV1": { "type": "object", "required": [ "version", "id", "type", "created", "account_code", "data" ], "properties": { "version": { "type": "string", "enum": [ "1.0" ] }, "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "visit.created", "visit.updated", "visit.ended", "visit.note.signed_and_sent", "visit.invoice.processed", "user.created", "visit.message.created" ] }, "created": { "type": "integer", "format": "int64", "description": "UNIX timestamp when the event was created" }, "account_code": { "type": "string" }, "data": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/VisitDataV1" }, { "$ref": "#/components/schemas/UserData" }, { "$ref": "#/components/schemas/VisitMessageDataV1" } ] } } }, "WebhookEventV2": { "type": "object", "required": [ "version", "id", "type", "created", "clinic_code", "data" ], "properties": { "version": { "type": "string", "enum": [ "2.0" ] }, "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "visit.created", "visit.updated", "visit.ended", "visit.note.signed_and_sent", "visit.invoice.processed" ] }, "created": { "type": "integer", "format": "int64", "description": "UNIX timestamp when the event was created" }, "clinic_code": { "type": "string" }, "data": { "oneOf": [ { "$ref": "#/components/schemas/VisitDataV2" }, { "$ref": "#/components/schemas/VisitNoteDataV2" }, { "$ref": "#/components/schemas/VisitInvoiceDataV2" } ] } } }, "VisitDataV1": { "type": "object", "properties": { "id": { "type": "string" }, "member_id": { "type": "string" }, "provider_id": { "type": "string", "nullable": true }, "start": { "type": "string", "description": "UNIX timestamp as string" }, "end": { "type": "string", "description": "UNIX timestamp as string" }, "actual_start": { "type": "string", "description": "UNIX timestamp as string" }, "actual_end": { "type": "string", "description": "UNIX timestamp as string" }, "status": { "type": "string" }, "completed_by": { "type": "string" } } }, "VisitDataV2": { "type": "object", "properties": { "id": { "type": "string" }, "member_id": { "type": "string" }, "provider_id": { "type": "string", "nullable": true }, "start": { "type": "integer", "format": "int64", "description": "UNIX timestamp" }, "end": { "type": "integer", "format": "int64", "description": "UNIX timestamp" }, "actual_start": { "type": "integer", "format": "int64", "description": "UNIX timestamp" }, "actual_end": { "type": "integer", "format": "int64", "description": "UNIX timestamp" }, "status": { "type": "string", "enum": [ "scheduled", "in_progress", "completed", "cancelled" ] }, "status_updated_by": { "type": "string" } } }, "VisitNoteDataV2": { "type": "object", "properties": { "id": { "type": "string" }, "member_id": { "type": "string" }, "provider_id": { "type": "string", "nullable": true }, "start": { "type": "integer", "format": "int64" }, "end": { "type": "integer", "format": "int64" }, "actual_start": { "type": "integer", "format": "int64" }, "actual_end": { "type": "integer", "format": "int64" }, "status": { "type": "string" }, "status_updated_by": { "type": "string" }, "note": { "$ref": "#/components/schemas/NoteData" } } }, "NoteData": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string", "enum": [ "new", "draft", "signed" ] } } }, "VisitInvoiceDataV2": { "type": "object", "properties": { "id": { "type": "string" }, "member_id": { "type": "string" }, "provider_id": { "type": "string", "nullable": true }, "start": { "type": "integer", "format": "int64" }, "end": { "type": "integer", "format": "int64" }, "actual_start": { "type": "integer", "format": "int64" }, "actual_end": { "type": "integer", "format": "int64" }, "status": { "type": "string" }, "status_updated_by": { "type": "string" }, "invoice": { "$ref": "#/components/schemas/InvoiceData" } } }, "InvoiceData": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "paid", "closed", "forgiven", "cancelled", "failed", "refunded" ] }, "amount_due": { "type": "integer", "description": "Amount in cents" }, "amount_paid": { "type": "integer", "description": "Amount in cents" }, "currency": { "type": "string" } } }, "UserData": { "type": "object", "properties": { "user_id": { "type": "string" }, "email": { "type": "string", "format": "email" }, "first_name": { "type": "string" }, "last_name": { "type": "string" } } }, "VisitMessageDataV1": { "type": "object", "description": "Payload of `visit.message.created`. A thin pointer — it deliberately carries no message content or PHI. Fetch the thread with GET /api/visits/{visit_id}/messages.", "required": [ "visit_id", "message_id", "actor_type", "ts" ], "properties": { "visit_id": { "type": "string", "description": "Visit whose message thread changed" }, "message_id": { "type": "string", "description": "The new message. De-duplicate on this — deliveries are retried up to 5 times, ~60s apart." }, "actor_type": { "type": "string", "enum": [ "patient", "provider" ], "description": "Who sent the message. Filter on this if you only want one direction." }, "ts": { "type": "integer", "format": "int64", "description": "UNIX timestamp when the message was created" } } } } } }