Skip to Content
Clinic APIWebhooks

Clinic Webhooks API

Endpoints for handling webhook integrations within the clinic system.

Twilio SMS Webhook

Handle incoming SMS messages from Twilio.

Endpoint: POST /v1/clinic/webhooks/twilio/sms
Authentication: Not required (webhook endpoint)

Request Body Parameters

This endpoint receives webhook data from Twilio when SMS messages are received. The parameters are automatically provided by Twilio’s webhook system.

ParameterTypeRequiredDescription
MessageSidstringYesUnique identifier for the message
FromstringYesPhone number that sent the message
TostringYesPhone number that received the message
BodystringYesContent of the SMS message
NumMediastringNoNumber of media files attached
MediaUrl0stringNoURL of first media attachment
MediaContentType0stringNoContent type of first media attachment

Example Webhook Payload

POST /v1/clinic/webhooks/twilio/sms HTTP/1.1
Content-Type: application/x-www-form-urlencoded
 
MessageSid=SM1234567890abcdef&From=%2B15551234567&To=%2B15559876543&Body=Hello%20from%20patient&NumMedia=0

Response Format

The webhook endpoint returns a TwiML response to control Twilio’s behavior:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Message>Thank you for your message. We will respond shortly.</Message>
</Response>

Webhook Security

Twilio Signature Validation

Twilio webhooks include a signature header for security validation:

X-Twilio-Signature: base64_encoded_signature

The system automatically validates this signature to ensure the webhook is from Twilio.

Webhook Processing

When an SMS webhook is received, the system:

  1. Validates the Twilio signature
  2. Identifies the patient based on the phone number
  3. Processes the message content for keywords or commands
  4. Routes the message to appropriate handlers
  5. Sends an automatic response if configured
  6. Logs the interaction for audit purposes

Common SMS Commands

Patients can send specific keywords to trigger automated responses:

  • HELP - Get help information
  • STOP - Unsubscribe from SMS notifications
  • START - Re-subscribe to SMS notifications
  • CONFIRM - Confirm an appointment
  • CANCEL - Request appointment cancellation
  • RESCHEDULE - Request appointment rescheduling

Error Handling

Invalid Phone Number

If the sender’s phone number is not found in the system:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Message>We don't recognize this phone number. Please contact our office directly.</Message>
</Response>

System Error

If there’s a system error processing the webhook:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Message>We're experiencing technical difficulties. Please try again later or call our office.</Message>
</Response>

Webhook Configuration

Twilio Setup

To configure Twilio webhooks:

  1. Set the webhook URL in your Twilio console
  2. Configure the HTTP method as POST
  3. Ensure the webhook URL is publicly accessible
  4. Set up signature validation for security

Required Twilio Configuration

Webhook URL: https://your-api-domain.com/v1/clinic/webhooks/twilio/sms
HTTP Method: POST
Content Type: application/x-www-form-urlencoded

Notes

  • Webhook endpoints do not require authentication as they use signature validation
  • All incoming SMS messages are logged for compliance and audit purposes
  • Automatic responses can be customized based on clinic preferences
  • The system handles both text messages and media attachments (images, documents)
  • Rate limiting may be applied to prevent abuse
  • Webhook failures are automatically retried by Twilio with exponential backoff
NotificationsPatients