Webhooks

Overview

Webhooks let you receive HTTP POST notifications when events happen in the Cara platform. Instead of polling the API, configure a webhook URL and we'll send events to you in real time.

Supported events

Event	Description
`patient_created`	A new patient record was created.
`patient_updated`	A patient record was updated.
`appointment_booked`	An appointment was booked.
`appointment_cancelled`	An appointment was cancelled.
`form_submitted`	A form submission was received.
`email_opened`	A tracked email was opened.
`email_clicked`	A link in a tracked email was clicked.

Webhook payload

All webhook payloads follow this structure:

{
  "event": "patient_created",
  "timestamp": "2025-01-15T10:30:00Z",
  "tenantId": "tenant_abc123",
  "data": {
    "id": "pat_abc123",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane.doe@example.com"
  }
}

Configuring webhooks

Configure your webhook URL in the platform under Settings > Integrations or via the API:

curl -X POST https://platform.caramedical.com/api/v1/settings/integrations \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "patientEhrWebhook": "https://your-app.com/webhooks/cara"
  }'

Verifying webhooks

Webhook requests include an x-cara-auth header with the N8N API key configured in your settings. Verify this header to ensure the webhook is authentic:

app.post('/webhooks/cara', (req, res) => {
  const signature = req.headers['x-cara-auth'];
 
  if (signature !== process.env.CARA_WEBHOOK_SECRET) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
 
  const { event, data } = req.body;
  // Handle the event...
 
  res.status(200).json({ received: true });
});

Best practices

Respond quickly — Return a 200 status within 5 seconds. Process events asynchronously.
Handle duplicates — Webhooks may be delivered more than once. Use idempotency keys.
Verify signatures — Always validate the x-cara-auth header.
Log everything — Keep logs of received webhooks for debugging.