Webhooks

Receive real-time notifications when events occur in your Relaya workspace. Register a URL and subscribe to specific event types.

Available Events

Event	Description
appointment.created	A new appointment was booked
appointment.updated	An appointment was rescheduled or modified
appointment.cancelled	An appointment was cancelled
patient.created	A new patient was registered
voice.call.completed	A voice call ended
voice.call.transferred	A call was transferred to staff
scribe.note.ready	A clinical note finished processing
scribe.note.approved	A clinical note was approved

POST/v1/webhooks

Request Body

Parameter	Type	Required	Description
url	string	Required	HTTPS endpoint URL to receive events
events	string[]	Required	Array of event types to subscribe to
secret	string	Optional	Signing secret for payload verification (auto-generated if omitted)
description	string	Optional	Optional description for this webhook

Example Request

curl -X POST "https://api.relaya.one/v1/webhooks" \
  -H "Authorization: Bearer rlya_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/relaya",
    "events": ["appointment.created", "appointment.cancelled", "voice.call.completed"],
    "description": "Main production webhook"
  }'

Example Response

{
  "data": {
    "id": "wh_5kn3m8",
    "url": "https://your-app.com/webhooks/relaya",
    "events": ["appointment.created", "appointment.cancelled", "voice.call.completed"],
    "secret": "whsec_a1b2c3d4e5f6g7h8i9j0",
    "description": "Main production webhook",
    "active": true,
    "created_at": "2026-07-25T10:00:00Z"
  }
}

GET/v1/webhooks

List all registered webhooks for your workspace.

DELETE/v1/webhooks/:id

Remove a webhook subscription. Events will no longer be delivered to this endpoint.

Payload Format

Webhook payloads are sent as POST requests with a JSON body:

{
  "id": "evt_9vm3k2",
  "type": "appointment.created",
  "created_at": "2026-07-25T10:00:00Z",
  "data": {
    "id": "apt_n3k8m2v1",
    "patient_id": "pat_4jn7h2",
    "doctor_id": "doc_9km3p1",
    "datetime": "2026-07-28T14:00:00Z",
    "status": "scheduled"
  }
}

Signature Verification

Each webhook includes a X-Relaya-Signature header containing an HMAC-SHA256 signature of the payload body using your webhook secret:

import hmac
import hashlib

def verify_webhook(payload_body, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload_body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Error Codes

Code	Status	Description
400	bad_request	Invalid URL or unsupported event type
401	unauthorized	Invalid or missing API key
404	not_found	Webhook not found
409	conflict	URL already registered
429	rate_limited	Too many requests