Skip to Content
Webhooks

Webhooks

Webhook endpoints for external system integrations.

Overview

Webhooks allow external systems to send real-time notifications to the Esteem platform. These endpoints are designed to receive data from third-party services and process them accordingly.

Twilio SMS Webhook

Handle incoming SMS messages from Twilio.

Endpoint: POST /v1/clinic/webhooks/twilio/sms
Authentication: Not required (uses signature validation)

Request Format

Twilio sends webhook data as application/x-www-form-urlencoded:

ParameterTypeDescription
MessageSidstringUnique identifier for the message
FromstringPhone number that sent the message
TostringPhone number that received the message
BodystringContent of the SMS message
NumMediastringNumber of media files attached
MediaUrl0stringURL of first media attachment (if any)
MediaContentType0stringContent type of first media (if any)

Example Webhook

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

Response Format

Returns TwiML 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>

Security

Signature Validation

All webhook endpoints validate incoming requests to ensure they’re from trusted sources:

  • Twilio: Uses X-Twilio-Signature header with SHA1-based signature
  • Signatures are validated against the raw request body and your webhook secret

IP Whitelisting

Consider implementing IP whitelisting for additional security:

Error Handling

Invalid Signature

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Message>Invalid request signature</Message>
</Response>

Processing Error

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

Configuration

Webhook URLs

Set these URLs in your external service configurations:

  • Twilio SMS: https://your-api-domain.com/v1/clinic/webhooks/twilio/sms

Required Settings

  • Ensure webhook URLs are publicly accessible
  • Configure HTTPS (required for production)
  • Set appropriate timeout values (recommended: 10-15 seconds)
  • Enable signature validation in your external service settings

Testing Webhooks

Local Development

For local testing, use tools like ngrok to expose your local server:

ngrok http 3000

Then use the ngrok URL for webhook configuration.

Webhook Testing Tools

  • Twilio Console: Test SMS webhooks directly from Twilio console
  • Postman: Create test requests with proper signatures
  • Webhook.site: Capture and inspect webhook payloads

Monitoring

Webhook Logs

All webhook requests are logged for monitoring and debugging:

  • Request headers and body
  • Response status and body
  • Processing time
  • Any errors encountered

Retry Logic

External services typically implement retry logic for failed webhooks:

  • Twilio: Retries up to 3 times with exponential backoff
  • Ensure your endpoints are idempotent to handle duplicate requests

Best Practices

  1. Validate Signatures: Always validate webhook signatures for security
  2. Handle Duplicates: Implement idempotency to handle duplicate webhooks
  3. Respond Quickly: Process webhooks asynchronously if heavy processing is needed
  4. Log Everything: Comprehensive logging helps with debugging and monitoring
  5. Graceful Degradation: Handle errors gracefully and provide meaningful responses

Notes

  • Webhook endpoints do not require standard API authentication
  • All webhook processing is logged for audit and debugging purposes
  • Failed webhook processing may trigger automatic retries from the external service
  • Consider implementing rate limiting to prevent abuse
Infrastructure