Webhooks: Events and contracts

Catalog of webhook events that MarIA emits to your backend and calls to the EHR/HIS

Webhooks allow your backend to receive real-time notifications of what happens during calls and appointment management. They are signed with HMAC-SHA256 to verify their origin.

MarIA → Client (events)

Event	When emitted	Typical action
appointment.created	After creating an appointment	Register in HIS, send patient confirmation
appointment.rescheduled	After rescheduling an appointment	Update in HIS, notify patient
appointment.cancelled	After cancelling an appointment	Update in HIS, release the slot
voice.call.status.updated	On each call status change	Update operational dashboard / KPIs
voice.call.escalated	When the call is transferred to a human	Alert the care team
voice.answer.updated	When a response is captured during a call	Sync with EHR or data warehouse
voice.transcript.created	When the call ends	Index transcript, quality assurance

EHR/HIS integration (MarIA calls your HIS)

MarIA invokes these webhooks on your hospital system during appointment management:

Webhook	Operation
appointment.getBenefits	Get available coverage/benefits
appointment.getSlots	Query available time slots
appointment.create	Create an appointment
appointment.cancel	Cancel an appointment
appointment.reschedulePending	Mark appointment as pending reschedule
appointment.getList	List a patient’s appointments
directory.centers	List available centers
directory.professionals	List professionals for a center/service
patient.authenticate	Verify patient identity
patient.onboard	Register a new patient

Registering webhooks

Register the endpoints where you want to receive MarIA events:

curl -X POST "$BASE_URL/webhooks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "appointment.created",
    "url": "https://your-backend.com/webhooks/maria",
    "auth": { "type": "hmac", "secret": "your-hmac-secret" }
  }'

Signature verification

All events carry the X-Integration-Signature: sha256=<hex> header computed over the RAW body. See HMAC Signature Verification for Node.js and Python code examples.

See the API Reference section for the full payload contracts of each event in the OpenAPI specification.