Webhooks and events
What a webhook is in Awell, the difference between events Awell sends out and webhooks sent to Awell, and what a payload contains.
A webhook is a message one system sends another when something happens, so nobody has to sit and check. Awell uses them in both directions.
Outbound webhooks report events; incoming webhooks start or advance care flows
| What happens | What it takes | |
|---|---|---|
| Outbound (Awell → another system) | Something happens in a care flow (a form is submitted, a care flow completes) and Awell posts an event to a URL the other system owns | A URL that can receive the message. See Receive webhook events |
| Incoming (another system → Awell) | Something happens in that system (a booking, a discharge) and it posts to an Awell URL to start or advance a care flow | A configured trigger. See Start a care flow from an incoming webhook |
Each page here says which direction it covers. The rest of this page is about outbound events.
An event reports one thing, once
activity.completed means a particular activity finished. It says nothing about what else changed, and
nothing about what comes next.
Every event carries the identifiers needed to look up the detail through the API: the care flow, the patient, and the object the event is about.
See the webhook event catalog for the full list.
Payloads carry identifiers, not clinical detail
Payloads are deliberately lean: they identify what happened and what it happened to, and they are not a copy of the patient record.
Keeping identifiers rather than clinical detail in transit limits what is exposed if an endpoint is ever misconfigured. Fetch the detail with the API using the identifiers in the event.
Delivery repeats, arrives out of order, and retries on failure
What that means for a listener:
- Order isn't guaranteed. Events can arrive out of sequence. Don't infer state from arrival order: read the event's own data.
- Delivery can repeat. The same event can arrive more than once, so handling must be idempotent: processing it twice should have the same result as once.
- Failures are retried. Awell retries with an increasing delay rather than giving up immediately.
Next steps
- Building the listener? → Receive webhook events
- Turning webhooks on for a care flow? → Configure webhooks in Studio
- Want the event list? → Webhook event catalog
Start a care flow from an incoming webhook
Let another system start a care flow by posting to an Awell URL: create the webhook, map payload data to baseline data points, attach a patient, and read the logs.
Receive webhook events
Build an endpoint that receives Awell's outbound webhook events: choose the events, verify the signature, respond correctly, then move from a test endpoint to production.