Webhooks and Events: Push Triggers and Receive Outcomes

Webhooks let your systems push events to Emma as they happen. When Emma receives a supported event, it automatically starts the matching workflow. Emma also fires outbound webhook events to your configured URL when a workflow completes, so your systems stay up to date without polling.

How webhooks work

Go to Emma → Integrations → No-Code Automation. Add the URL where Emma should send outcome events and copy your inbound webhook URLs for use in the next step.

Subscribe in your platform

In your forms platform, EMR, or payment system, subscribe to the relevant event (for example, forms.abandoned) and point it at your Emma inbound URL.

Emma receives the event

Emma parses the payload, matches it to the configured workflow, and starts execution automatically.

Emma sends the outcome

When the workflow completes, Emma POSTs the outcome event to your registered outbound URL.

Inbound events Emma accepts

Event	Trigger
`forms.abandoned`	A patient dropped off before completing a form or checkout
`forms.completed`	A patient completed a form (cancels any pending recovery)
`appointment.created`	A new appointment was booked
`appointment.approaching`	An appointment is coming up soon
`payment.failed`	A payment transaction failed
`prescription.status_changed`	A prescription or fulfillment status changed
`patient.follow_up_required`	A follow-up action is needed for a patient

Inbound event URLs and payloads

Emma exposes per-clinic inbound webhook URLs. Use the URLs from the Integrations page to point your platform at the correct endpoint for each event type.

POST /api/n8n/webhook/{clinicId}/forms-abandoned
x-n8n-secret: <your-inbound-secret>
Content-Type: application/json

{
  "sessionId": "sess_8f2c...",
  "patientFirstName": "Jordan",
  "patientLastName": "Lee",
  "phone": "+15551234567",
  "resumeUrl": "https://your-platform.example/resume/sess_8f2c..."
}

POST /api/n8n/webhook/{clinicId}/forms-completed
x-n8n-secret: <your-inbound-secret>
Content-Type: application/json

{
  "sessionId": "sess_8f2c...",
  "patientFirstName": "Jordan",
  "patientLastName": "Lee"
}

Securing inbound webhooks

Emma uses a shared secret to verify that inbound requests originate from a trusted source. Each inbound webhook URL has an associated secret generated on the Integrations page. Your platform must include this secret in every request:

x-n8n-secret: <your-inbound-secret>

Always validate the inbound secret before processing a webhook payload. Requests missing or presenting a wrong secret should be rejected with a 401.

Outbound webhook events

When a workflow finishes, Emma POSTs an outcome event to your registered outbound URL. The payload includes the clinic, a timestamp, and structured outcome data you can use to update your own records or trigger downstream actions.

`recovery_case.created`

Emma fires this event as soon as it creates a recovery case — before any outreach attempt is made. Use it to log or display the pending case in your system.

{
  "event": "recovery_case.created",
  "clinicId": "clinic_abc123",
  "sentAt": "2026-09-24T14:20:05Z",
  "data": {
    "recoveryCaseId": "rc_41d0...",
    "sessionId": "sess_8f2c...",
    "patientFirstName": "Jordan",
    "patientLastName": "Lee"
  }
}

`recovery_case.outcome`

Emma fires this event when a recovery workflow reaches a terminal state. Use it to update your system of record with the final outcome.

{
  "event": "recovery_case.outcome",
  "clinicId": "clinic_abc123",
  "sentAt": "2026-09-24T14:27:41Z",
  "data": {
    "recoveryCaseId": "rc_41d0...",
    "sessionId": "sess_8f2c...",
    "recoveryStatus": "RECOVERED"
  }
}

Recovery status values

`recoveryStatus`	Meaning
`RECOVERED`	Patient agreed to finish; resume link sent
`FOLLOW_UP_REQUIRED`	Patient wants a callback or needs more time
`PRICING_ESCALATION`	Needs someone from the billing team
`CLINICAL_ESCALATION`	Needs someone from the care team
`PATIENT_NOT_INTERESTED`	Patient declined to continue
`PATIENT_NOT_REACHED`	Patient could not be reached
`ALREADY_COMPLETED`	Patient finished before Emma called

Idempotency

Emma deduplicates incoming events by session ID. Sending the same forms.abandoned event twice for the same session creates only one recovery case — so you don’t need to worry about accidental duplicate triggers from your platform.

When to use webhooks

Use webhooks when your system needs to notify Emma that something happened. If you need to request an action on demand and wait for a response, use the REST API instead.

Overview

Integration Methods

Workflow Guides

Webhooks and Events: Push Triggers and Receive Outcomes

How webhooks work

Inbound events Emma accepts

Inbound event URLs and payloads

Securing inbound webhooks

Outbound webhook events

`recovery_case.created`

`recovery_case.outcome`

Recovery status values

Idempotency

When to use webhooks

​How webhooks work

​Inbound events Emma accepts

​Inbound event URLs and payloads

​Securing inbound webhooks

​Outbound webhook events

​recovery_case.created

​recovery_case.outcome

​Recovery status values

​Idempotency

​When to use webhooks

How webhooks work

Inbound events Emma accepts

Inbound event URLs and payloads

Securing inbound webhooks

Outbound webhook events

`recovery_case.created`

`recovery_case.outcome`

Recovery status values

Idempotency

When to use webhooks