# Webhooks and events
URL: https://docs.awellhealth.com/docs/automate-with-events/webhooks-and-events

> For the complete documentation index, see [llms.txt](https://docs.awellhealth.com/llms.txt).





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 [#outbound-webhooks-report-events-incoming-webhooks-start-or-advance-care-flows]

<img alt="The Incoming webhooks tab under Integrations, listing each webhook with the extension and event that drives it" src="__img0" />

|                                       | 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](/docs/automate-with-events/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](/docs/automate-with-events/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 [#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](/docs/automate-with-events/webhook-event-catalog) for the full list.

## Payloads carry identifiers, not clinical detail [#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 [#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 [#next-steps]

* **Building the listener?** → [Receive webhook events](/docs/automate-with-events/receive-webhook-events)
* **Turning webhooks on for a care flow?** → [Configure webhooks in Studio](/docs/automate-with-events/configure-webhooks-in-studio)
* **Want the event list?** → [Webhook event catalog](/docs/automate-with-events/webhook-event-catalog)